301 lines
17 KiB
Markdown
301 lines
17 KiB
Markdown
<!-- Improved compatibility of К началу link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
|
||
<a id="readme-top"></a>
|
||
<!--
|
||
*** Thanks for checking out the Best-README-Template. If you have a suggestion
|
||
*** that would make this better, please fork the repo and create a pull request
|
||
*** or simply open an issue with the tag "enhancement".
|
||
*** Don't forget to give the project a star!
|
||
*** Thanks again! Now go create something AMAZING! :D
|
||
-->
|
||
|
||
|
||
<!-- PROJECT LOGO -->
|
||
<br />
|
||
<div align="center">
|
||
<!-- <a href="https://github.com/othneildrew/Best-README-Template"> -->
|
||
<img src="Logo-Futriix.png" height=100></img>
|
||
</a>
|
||
|
||
<h3 align="center">Futriix</h3>
|
||
|
||
<p align="center">
|
||
Futriix's полная документация (команды идентичны)
|
||
<br />
|
||
<a href="https://docs.keydb.dev/"><strong>Изучить полную документацию</strong></a>
|
||
<br />
|
||
<a href="">Сообщить об ошибке</a>
|
||
·
|
||
<a href="">Предложение новой функциональности</a>
|
||
</p>
|
||
</div>
|
||
|
||
## Краткая документация проекта Futriix
|
||
|
||
<!-- TABLE OF CONTENTS -->
|
||
<br>
|
||
<details>
|
||
<summary><b>Содержание</b></summary>
|
||
<ol>
|
||
<li>
|
||
<a href="#о-проекте">О проекте</a>
|
||
<li><a href="#лицензия">Лицензия</a></li>
|
||
<li><a href="#основные-термины">Основные термины</a></li>
|
||
<li><a href="#подготовка">Подготовка</a></li>
|
||
<li><a href="#компиляция">Компиляция</a></li>
|
||
<li><a href="#тестирование-сборки">Тестирование сборки</a></li>
|
||
<li><a href="#пример-основных-команд">Пример основных команд</a></li>
|
||
<li><a href="#кластер">Кластер</a></li>
|
||
<li><a href="#типовые-проблемы">Типовые проблемы</a></li>
|
||
<li><a href="#дорожная-карта">Дорожная карта</a></li>
|
||
<li><a href="#вклад">Вклад</a></li>
|
||
<li><a href="#контакты">Контакты</a></li>
|
||
</ol>
|
||
</details>
|
||
|
||
<!-- ABOUT THE PROJECT -->
|
||
## О проекте
|
||
|
||
Проект Futriix является форком проекта KeyDB.
|
||
|
||
Futriix-Мультимодельная СУБД на языке С поддержкой плагинов на языке Golang.
|
||
Ниже приведён пример того, инструкции по настройке вашего проекта локально.
|
||
Чтобы запустить локальную копию проекта, выполните следующие простые шаги.
|
||
|
||
<!-- LICENSE -->
|
||
## Лицензия
|
||
|
||
Проект распространяется под 3-пунктной лицензией BSD. Подробнсти смотрите в файле `COPYING.txt`.
|
||
|
||
## Основные термины
|
||
|
||
* **Инстанс**- запущенный экземляр базы данных
|
||
* **Узел (нода)**- мощный сервер
|
||
* **Кластер**- группа компьютеров, объединённых высокоскоростными каналами связи и представляющая с точки зрения пользователя единый аппаратный ресурс
|
||
* **База Данных(БД)**-массив информация, хранящийся, например, на флешке, в файле, на кластере
|
||
* **Система Управления Базами Данных(СУБД)**- Это программа для внесения изменений в базу данных и поиска по ней
|
||
|
||
|
||
## Подготовка
|
||
|
||
**Для операционных систем семейства Debian** выполните следующие шаги:
|
||
* Устанавливаем язык программирования C/C++, соопутствующие утилиты (autoconf и другие)
|
||
|
||
```sh
|
||
unix:$ sudo apt update
|
||
unix:$ sudo apt upgrade
|
||
unix:$ sudo apt install build-essential nasm autotools-dev autoconf libjemalloc-dev tcl tcl-dev uuid-dev libcurl4-openssl-dev git hugepages
|
||
```
|
||
|
||
* Устанавливаем язык программирования Golang по инструкции с [официального сайта](https://go.dev/doc/install)
|
||
|
||
|
||
## Компиляция
|
||
|
||
1. Копируем репозиторий
|
||
```sh
|
||
unix:$ git clone https://source.futriix.ru/gvsafronov/Futriix
|
||
```
|
||
2. Переходим в каталог с исходном кодом src
|
||
```sh
|
||
unix:$ cd src/
|
||
```
|
||
3. Компилируем Futriix с помощью утилиты Make
|
||
```sh
|
||
unix:$ make
|
||
```
|
||
Futriix может быть скомпилирован для следующих операционных систем: Linux, OSX, OpenBSD, NetBSD, FreeBSD.
|
||
Мы поддерживаем архитектуры endian и little endian, и 32-битные и 64-битные системы.
|
||
|
||
### Дополнительные параметры компиляции
|
||
|
||
Для сборки проекта с поддержкой TLS выпоните команду:
|
||
```sh
|
||
unix:$ make BUILD_TLS=yes
|
||
```
|
||
Для сбоки проекта с поддержкой TLS, в качестве модуля, выполните команду:
|
||
```sh
|
||
unix:$ make BUILD_TLS=module
|
||
```
|
||
Для выполнения данной операции вам необходимо библиотека OpenSSL (например,
|
||
libssl-dev для Debian/Ubuntu).
|
||
|
||
<p align="right">(<a href="#readme-top">К началу</a>)</p>
|
||
|
||
## Тестирование сборки
|
||
|
||
После компиляции Futriix, рекомендуем запустить утилиту для проверки корректности сборки:
|
||
```sh
|
||
unix:$ make test
|
||
```
|
||
## Исправление проблем сборки с зависимостями или кэшированными параметрами сборки.
|
||
|
||
Futriix содержит некоторые зависимости, которые хранятся в директории `deps`.
|
||
Утилита `make` автоматически не пересобирает зависимости даже если вносятся каие-либо изменения в код зависимостей.
|
||
|
||
Когда вы обновляете код проекта командой `git pull` или когда код внутри
|
||
дерева зависимостей изменен каким-либо другим способом, обязательно используйте следующее
|
||
команду для того, чтобы действительно все почистить и пересобрать с нуля:
|
||
```sh
|
||
unix:$ make distclean
|
||
```
|
||
В результате работы команды выше будут очищены: аллокатор памяти jemalloc, язык lua, библиотеку hiredis, библиотеку linenoise а также другие зависимости.
|
||
|
||
Кроме того, если вы принудительно используете определенные параметры сборки, такие как 32-битная версия для 32-битной системы, оптимизации компилятора C в данном случае не будут выполнены. Оптимизации (для целей отладки) и другие подобные параметры времени сборки,
|
||
кэшируются на неопределенный срок, пока вы не выполните команду `make distclean`.
|
||
|
||
<p align="right">(<a href="#readme-top">К началу</a>)</p>
|
||
|
||
## Аллокатор
|
||
|
||
Выбор аллокатора памяти не по умолчанию при сборке Futriix выполняется путем установки
|
||
параметра `MALLOC` переменной окружения. Futriix компилируется и компонуется с libc
|
||
malloc по умолчанию, за исключением jemalloc, который используется по умолчанию в дистрибутивах Linux.
|
||
Это значение по умолчанию было выбрано потому, что в jemalloc меньше
|
||
проблем c фрагментацией, чем libc malloc.
|
||
|
||
Чтобы принудительно скомпилировать libc malloc, выполните следующую команду:
|
||
```sh
|
||
unix:$ make MALLOC=libc
|
||
```
|
||
Для компиляции аллокатора jemalloc на операционной системе Mac OS X, выполните команду:
|
||
|
||
```sh
|
||
unix:$ make MALLOC=jemalloc
|
||
```
|
||
|
||
<!-- USAGE EXAMPLES -->
|
||
## Пример основных команд
|
||
В данном разделе приведён пример основных команд субд Futriix
|
||
|
||
Запускаем клиент Futriix, перейдя в каталог с исходным кодом:
|
||
```sh
|
||
unix:$ cd src && ./futriix-cli
|
||
```
|
||
|
||
Проверяем доступность сервера, выполняяя команду `ping`, если будет получен ответ `pong`-значит сервер доступен и работает корректно
|
||
```sh
|
||
127.0.0.1:futriix:~> ping
|
||
PONG
|
||
```
|
||
Присваеваем значение переменной `foo` равное `bar`, командой ниже:
|
||
```sh
|
||
127.0.0.1:futriix:~> set foo bar
|
||
OK
|
||
```
|
||
|
||
Получаем значение переменной `foo`, командой ниже:
|
||
```sh
|
||
unix:$ get foo
|
||
"bar"
|
||
```
|
||
|
||
<p align="right">(<a href="#readme-top">К началу</a>)</p>
|
||
|
||
## Кластер
|
||
|
||
1. Откройте директорию с Futriix:
|
||
```sh
|
||
unix:$ cd futriix
|
||
```
|
||
2. Откройте файл конфигурации futriix.conf в любом текстовом редакторе, например nano, как в примере приведённом ниже:
|
||
```sh
|
||
unix:$ nano futriix/futriix.conf
|
||
```
|
||
3. Найдите и установите значения "yes" для параметров "active-replica" и "multi-master". После чего добавьте в файл конфигурации ip-адреса, узлов вашего кластера.
|
||
Если вы всё сделали правильно у вас должны отобразится строки в файле конфигурации `futriix.conf` как показано ниже:
|
||
```sh
|
||
active-replica yes
|
||
multi-master yes
|
||
replicaof 192.168.11.5 9880
|
||
replicaof 192.168.11.6 9880
|
||
replicaof 192.168.11.7 9880
|
||
```
|
||
4. Сохраните внесённые вами изменения, выйдите из редактора, воспользовавшись командами ниже:
|
||
```sh
|
||
unix:$ ctrl+O
|
||
unix:$ ctrl+x
|
||
```
|
||
5. Перейдите в директорию Futriix и запустите скрипт `cluster.sh` с параметрами `pick` (скрипт запущенный с данным параметром "соберёт кластер"), и `run`,(скрипт запущенный с данным параметром "запустит кластер") как указано ниже:
|
||
```sh
|
||
unix:$ ./cluster pick
|
||
unix:$ ./cluster run
|
||
```
|
||
6. Для остановки кластера запустите скрипт `cluster.sh` с параметром `stop`
|
||
```sh
|
||
unix:$ ./cluster stop
|
||
```
|
||
<p align="right">(<a href="#readme-top">К началу</a>)</p>
|
||
|
||
## Типовые проблемы
|
||
|
||
В данном разделе описаны типовые проблемы, возникающие при эксплуатации субд Futrix.
|
||
|
||
1. **Описание проблемы:** При запуске инстанса Futriix, появляется следующее сообщение:
|
||
```sh
|
||
Warning: no config file specified, using the default config. In order to specify a config file use ./futriix-server /path/to/futriix.conf
|
||
```
|
||
|
||
**Решение:**
|
||
|
||
При запуске инстанса сервера futriix, указать корректный путь до файла конфигурации, командой ниже:
|
||
```sh
|
||
unix:$ ./futriix-server /path/to/futriix.conf
|
||
```
|
||
|
||
2. **Описание проблемы:** При запуске инстанса Futriix, появляется следующее сообщение:
|
||
```sh
|
||
1:12:S 18 Apr 2025 04:47:25.643 # NOTICE: Detuning locks due to high load per core: 97.49%
|
||
1:12:S 18 Apr 2025 04:47:55.491 # NOTICE: CPU pressure reduced
|
||
```
|
||
|
||
**Решение:**
|
||
|
||
Семантика захвата/освобождения не важна для детюнинга. Суть этого сообщения в том, что futriix пытается корректно обработать ситуацию с превышением нагрузки на ЦП. Это штатная ситуация, и она не является ошибкой и не вызывает проблем.
|
||
|
||
Futriix использует спинлоки для быстрой синхронизации. Когда нагрузка на ЦП превышает 100% на ядро, ядро может неосознанно предоставить время ЦП заблокированному потоку, который находится в состоянии ожидания, вместо активного потока. Это приводит к значительно большей задержке.
|
||
|
||
Когда такая ситуация обнаруживается, Futriix будет крутиться в ожидании меньшего времени, прежде чем приостановить поток. Это приводит к лучшей пропускной способности, когда время ЦП ограничено. Однако «правильным» решением является обеспечение того, чтобы время ЦП не было так ограничено.
|
||
|
||
<p align="right">(<a href="#readme-top">К началу</a>)</p>
|
||
|
||
<!-- ROADMAP -->
|
||
## Дорожная карта
|
||
|
||
- [x] Добавить поддержку хранимых процедур
|
||
- [x] Добавить поддержку многопоточности
|
||
- [x] Изменить приглашение командной строки клиента futriix-cli
|
||
- [x] Переписать скрипт cluster.sh, формирующий кластер Futriix
|
||
- [x] Добавить поддержку модуля для работы с JSON
|
||
- [x] Удалить поддержку Sentinel
|
||
- [x] Добавить поддержку хранимых процедур
|
||
- [x] Добавить поддержку языка запросов SQL
|
||
- [ ] Реализовать поддержку алгоритма Raft
|
||
- [ ] Реализовать планировщик задач,основанный на вытесняющей многозадачности
|
||
- [ ] Реализовать поддержку ACID-транзакций
|
||
|
||
См. [Открытые проблемы](https://source.futriix.ru/gvsafronov/Futriix/issues) полный список предлагаемых функций (и известных проблем).
|
||
|
||
<p align="right">(<a href="#readme-top">К началу</a>)</p>
|
||
|
||
<!-- CONTRIBUTING -->
|
||
## Вклад
|
||
|
||
Вклады — это то, что делает сообщество открытого исходного кода таким замечательным местом для обучения, вдохновения и творчества. Любой ваш вклад **очень ценится**.
|
||
|
||
Если у вас есть предложение, которое могло бы улучшить ситуацию, создайте форк репозитория и создайте запрос на включение. Также можно просто открыть задачу с тегом «улучшение».
|
||
Не забудьте поставить проекту звезду! Еще раз спасибо!
|
||
|
||
1. Форкните проект
|
||
2. Создайте свою ветку функций (`git checkout -b Feature/AmazingFeature`)
|
||
3. Зафиксируйте свои изменения (git commit -m 'Add some AmazingFeature'`)
|
||
4. Отправьте в ветку (`git push origin Feature/AmazingFeature`)
|
||
5. Откройте запрос на включение
|
||
|
||
<!-- CONTACT -->
|
||
## Контакты
|
||
|
||
Григорий Сафронов - [E-mail](gvsafronov@yandex.ru)
|
||
|
||
Ссылка на проект (https://source.futriix.ru/gvsafronov/Futriix)
|
||
|
||
<p align="right">(<a href="#readme-top">К началу</a>)</p> |