diff --git a/README.md b/README.md new file mode 100644 index 0000000..30a3e32 --- /dev/null +++ b/README.md @@ -0,0 +1,469 @@ + + + + + + +
+
+ + + + +

Futriix

+ +

+ Проект futriix это мультимодельная NOSQL субд с очередями без блокировок
+
+
+ +

+
+ + ## Краткая документация проекта Futriix + + +
+ + Содержание
+
    +
  1. + О проекте +
  2. Лицензия
    3. +
  3. Основные термины
    4. +
  4. Подготовка
    5. +
  5. Компиляция
    6. +
  6. Примеры основных команд
    7. +
  7. Репликация
    8. +
  8. Резервное копирование
    9. +
  9. Http API
    10. +
  10. Lua-скрипты
    11. +
  11. Проблемы
    12. +
  12. Дорожная карта
    13. +
  13. Вклад
    14. +
  14. Контакты
    15. +
+ + + +## О проекте + +Futriix это мультимодельная NOSQL субд без блокировок написанная на языке программирования Rust. +Поддерживает следующие модели хранения данных: модель временных рядов (time series), документную, ключ-значение. +Для расщирения базового функционала имеет встроенный lua-интепретатор. +Futriix является резидентной субд, т.е. хранящей свои данные в оперативной памяти, с их периодическим сохранением на внутренний носитель: HDD (жёсткий диск) или SSD-накопитель. + + + +## Лицензия + +Проект распространяется под 3-пунктной лицензией BSD. Подробнсти смотрите в файле `LICENSE.txt`. + +## Основные термины + +* **База Данных(БД)** -массив информация, хранящийся, например, на флешке, в файле, на кластере +* **Система Управления Базами Данных(СУБД)** - Это программа для внесения изменений в базу данных и поиска по ней +* **Мультимодельная СУБД** - Это субд, поддерживающая одновременно несколько моделей хранения данных +* **Резидентная СУБД** - субд, хранящая все свои данные в оперативной памяти, с периодическим сохранением на HDD или SSD +* **Инстанс** - запущенный экземляр базы данных +* **Узел (хост,нода)** - физический сервер +* **Таппл** - аналог документа в любой документно-ориентированной субд +* **Репликасет** - группа актуальных данных,хранящиеся на нескольких узлах +* **Временные ряды (time series) ** - это данные, последовательно собранные в регулярные промежутки времени, полученные из какого-либо устройства (цены на акции, данные температуры, объёмы продаж и.т.д.) +* **Кластер** - группа компьютеров, объединённых высокоскоростными каналами связи и представляющая с точки зрения пользователя единый аппаратный ресурс +* Команды, выполняемые с привилегиями суперпользователя (root), отмечены символом приглашения **«#»** +* Команды, выполняемые с правами обычного пользователя(user), отмечены символом приглашения **«$»** +* **FutBot** - интеллектуальный помощник в мессенджере Телеграмм, помогающий осущесвлять быстрый поиск по документации проекта + + +## Подготовка + +**Для операционных систем семейства Debian** выполните следующие шаги: +* Устанавливаем язык программирования Rust + + ```sh + # apt update + # apt upgrade + # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +**Для операционных систем семейства Red Hat (Fedora, Aurora)** выполните следующие шаги: +* Устанавливаем язык программирования Rust + + ```sh + # dnf update + # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +**Для операционной системы Alpine** выполните следующие шаги: +* Устанавливаем язык программирования Rust + + ```sh + # apk update + # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +## Компиляция + +1. Копируем репозиторий + ```sh + $ git clone https://source.futriix.ru/gvsafronov/futriix + ``` +2. Переходим в каталог с исходном кодом src + ```sh + $ cd futriix/ + ``` +3. Компилируем Futriix с помощью пакетного менеджера `Cargo` + ```sh + $ cargo build + ``` +4. Для запуска тестов запускаем команды: + ```sh + $ cargo test --test integration # запуск только интеграционных тестов + $ cargo test --bench benches # запуск только бенчмарков + ``` + +> [!WARNING] +> **Futriix также может быть скомпилирован для следующих операционных систем: `Linux`, `OSX`, `Open Indiana`, `FreeBSD`, но сборка для этих операционных систем не проводилась!!!** + + +## Примеры основных команд + +В данном разделе приведён пример основных команд субд Futriix + +Запускаем клиент Futriix, перейдя в каталог с исходным кодом: + ```sh + $ cd /target/realease && ./futriix-cli + ``` + +Проверяем доступность сервера, выполняяя команду `insert`, если будет получен ответ `successful`-значит вставка данных работает корректно + + ```sh +futriix:~> insert user1 {"name": "Alice", "age": 25} +Insert successful + ``` + +Считываем значение таппла `user1` командой ниже `get`: + ```sh + futriix:~> get user1 +{ + "age": 25, + "name": "Alice" +} + + ``` + +Изменим значение переменных `name`, `age`, командой ниже: + ```sh +futriix:~> update user5 '{"name": "Alice Smith", "age": 26}' +Update successful + + ``` +Удалим весь таппл + ```sh + futriix:~> delete user1 + Delete successful + ``` + + Посмотрим как работают транзакции (создание, откат, коммит) + ```sh + futriix:~> begin + Transaction started + + futriix:~> insert user3 {"name": "Charlie", "age": 40} + Insert successful + + futriix:~> rollback + Transaction aborted + + futriix:~> insert user3 {"name": "Peter", "age": 32} + + futriix:~> commit + Transaction committed + ``` + Создадим индекс для поля `age` в таппле user3, а потом удалим его + ```sh + futriix:~> createindex age + Index created on field 'age' + + futriix:~> dropindex age + Index dropped + ``` + +

(К началу)

+ +## Репликация + +1. Включите репликацию в конфигурационном файле `futriix.config.toml`, установив enabled = true в секции [replication] в файле конфигурации + `futriix.config.toml` + ```sh + [replication] + enabled = false # Включена ли репликация + peer_nodes = [] # Список узлов для репликации (например ["192.168.1.2:8080"]) + sync_interval = 1000 # Интервал синхронизации в мс + ``` +2. Откройте файл конфигурации `futriix.config.toml` в любом текстовом редакторе, например nano, если вы всё сделали правильно, он должен выглядеть так: + ```sh + $ nano futriix/futriix.conf.toml + ``` + ```sh + [server] + ip = "127.0.0.1" # IP-адрес сервера (0.0.0.0 для доступа из сети) + port = 8080 # Порт для TCP-сервера + log_path = "futriix.log" # Путь к лог-файлу + + [client] + ip = "127.0.0.1" # IP для клиента (обычно localhost) + port = 8080 # Порт клиента (должен совпадать с серверным) + + [replication] + enabled = false # Включена ли репликация + peer_nodes = [] # Список узлов для репликации (например ["192.168.1.2:8080"]) + sync_interval = 1000 # Интервал синхронизации в мс + + [http_api] + enabled = true # Включить HTTP API + port = 8081 # Порт для HTTP API (обычно на 1 больше основного) + + ``` +4. Сохраните внесённые вами изменения, после чего репликация будет доступна в субд, выйдите из редактора, воспользовавшись командами ниже: + ```sh + $ ctrl+O + $ ctrl+x + ``` +5. Также для включения репликации вы можете использовать команду в `futriix-cli`: + ```sh + + futriix:~> replication on + ``` + Сервер автоматически начнёт синхронизацию с указанными пирами (peer_nodes) с заданным интервалом (sync_interval). + + После включения сервер будет периодически отправлять команды из истории (command_history) на все пиры для поддержания согласованности данных. + + + ### Команды для управления репликацией + + В проекте добавлены следующие команды для управления репликацией: + ```sh + replication on — включить репликацию + replication off — выключить репликацию + replication status — получить статус репликации (включена/выключена, список пиров, время последней синхронизации) + replication add-peer — добавить пир для репликации (например, replication add-peer 127.0.0.1:8081) + replication remove-peer — удалить пир из списка репликации + ``` + + +## Резервное копирование + + Для создания и восстановления из бекапа используются команды futload (восстановление из бэкапа) и futunload (создание бэкапа). + Вот примеры использования команд futload (восстановление из бэкапа) и futunload (создание бэкапа) в Futriix CLI: + +futunload - Создание бэкапа + + ```sh + + futunload <путь_к_файлу_бэкапа> +``` + +Пример 1: Создать бэкап в текущей директории +```sh +futunload ./backups/snapshot_2024.fut + +Вывод при успехе: +text + +Backup created successfully at ./backups/snapshot_2024.fut +``` + +Пример 2: Создать бэкап с абсолютным путём + +```sh +futunload /var/backups/futriix/db_export.fut +``` + +2. futload - Восстановление из бэкапа + +Формат команды: +bash +```sh +futload <путь_к_файлу_бэкапа> +``` + +Пример 1: Восстановить из локального файла +bash +```sh +futload ./backups/snapshot_2024.fut + +Вывод при успехе: +text + +Backup restored successfully from ./backups/snapshot_2024.fut +``` + +Пример 2: Восстановить из системного пути +```sh +futload /mnt/backups/prod_db.fut + + ``` + +

(К началу)

+ + +## Http API + +Добавление данных: + + ```sh + +curl -X POST http://localhost:8081/api/insert \ + -d '{"user_42": {"name":"John", "age":30}}' +``` + +Получение данных: + +```sh +curl -X GET http://localhost:8081/api/get/user_42 + +{"name":"John","age":30} +``` +```sh +Пакетное обновление: + +curl -X POST http://localhost:8081/api/update \ + -d '{"user_42": {"age":31}, "product_5": {"price":99}}' + + ``` +Пример Python-программы с использованием Http-API: + +```sh +import requests +BASE_URL = "http://localhost:8081/api" +def set_value(key, value): + requests.post(f"{BASE_URL}/insert", json={key: value}) +def get_value(key): + return requests.get(f"{BASE_URL}/get/{key}").json() + +``` + +

(К началу)

+ + +## Lua-скрипты + +> [!CAUTION] +> **Поддержка работы lua в настоящий момент эксперементальная и может вызвать аварийное завершение сервера!!!** + +1. Интерактивный режим работы, (выполнение скрипта в клиенте `futriix-cli`): + +```sh + futriix:~> futexec +lua> return "Hello, " .. os.date("%Y-%m-%d") +``` + +2. Выполнение файлов скриптов (c помоью команды в клиенте `SysExec`): + + ```sh + futriix:~> sysexec my_script + + ```` + +3. Доступ к данным из сервера Lua на примера lua-скрипта для чтение и записи данных из субд + +Скрипты имеют доступ к специальному API: + +```sh +-- read.lua +-- Чтение данных +local value = futriix.get("my_key") + +-- Запись данных +futriix.put("temp_key", {data = "test", ts = os.time()}) + +-- Пример сложной логики +for i = 1, 10 do + futriix.put("counter/"..i, i*2) +end +``` + +

(К началу)

+ + +## Проблемы + +В данном разделе описаны типовые проблемы, возникающие при эксплуатации субд Futrix. + +1. **Описание проблемы:** После запуска futriix, в лог-файле `futriix.log` дата указывается без указания текущего года: + ```sh + 11:29:49 [INFO] Futriix Server started successfully + 11:29:49 [INFO] Listening on: 127.0.0.1:8080 + ``` + +**Решение:** +```sh +На данный момент это выявленный программный баг, нужно ждать выпуска новой версии. :-)) +``` + +

(К началу)

+ + +## Дорожная карта + +- [x] Реализовать поддержку хранимых процедур +- [x] Реализовать поддержку многопоточности +- [x] Реализовать неблокирующие чтение/запись +- [x] Реализовать мульти-мастер асинхронную репликацию через файл конфигурации +- [x] Реализовать логирование +- [x] Реализовать команды сервера для управления репликацией +- [x] Реализовать поддержку первичных индексов +- [x] Реализовать поддержку протокола MessagePack +- [x] Реализовать поддержку транзакций +- [x] Добавить механизм сторонних модулей на языке lua, расширяющих базовый функционал сервера +- [x] Добавить макет интеллектуального помощника FutBot +- [x] Реализовать проверку запуска сервера при запуске клиента (если сервер НЕ запущен клиент не запускается) +- [x] Реализовать поддержку HTTP-restfull API +- [x] Исправить ошибки записи журнала логов (в журнал лога кроме текущего времени добавить текущий год) +- [ ] Реализовать утилиту тестирования сервера на количество запросов на чтение/запись +- [ ] Реализовать поддержку алгоритма Raft +- [ ] Реализовать поддержку SQL +- [ ] Реализовать поддержку вторичных индексов +- [ ] Реализовать поддержку ACID-транзакций +- [ ] Реализовать полноценного интеллектуального помощника FutBot, задачами которого будут быстрый поиск ответов на вопросы, возникающие при эксплуатации субд Futrix. + +См. [Открытые проблемы](https://source.futriix.ru/gvsafronov/futriixw/issues) полный список предлагаемых функций (и известных проблем). + +

(К началу)

+ + + + + + +## Вклад + +Вклады — это то, что делает сообщество открытого исходного кода таким замечательным местом для обучения, вдохновения и творчества. Любой ваш вклад **очень ценится**. + +Если у вас есть предложение, которое могло бы улучшить ситуацию, создайте форк репозитория и создайте запрос на включение. Также можно просто открыть задачу с тегом «улучшение». + + +1. Форкните проект +2. Создайте свою ветку функций (`git checkout -b Feature/AmazingFeature`) +3. Зафиксируйте свои изменения (git commit -m 'Add some AmazingFeature'`) +4. Отправьте в ветку (`git push main Feature/AmazingFeature`) +5. Откройте запрос на включение + + +## Контакты + +Григорий Сафронов - [E-mail](gvsafronov@yandex.ru) + +Ссылка на Интеллектуальный помощник - [FutBot](https://t.me/Futriix_bot) + +

(К началу)