flusql/README.md

<!-- 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.png" height=100 alt="Logo.png"></img>
  </a>

  <h3 align="center">fluSQL</h3>

  <p align="center">
   <b>fluSQL-Автономный модуль для  распределённой субд "futriix" добавляющий в неё функционал языка SQL, написанный на языке Rust</b> <br>
    <br />
    <br />
  <!--   <a href="">Сообщить об ошибке</a> 
    &middot;
 <!--    <a href="">Предложение новой функциональности</a> -->
  </p>
</div>

  ## Краткая документация проекта fluSQL

<!-- TABLE OF CONTENTS -->
<br>
<!-- <details> -->
  <summary><b>Содержание</b></summary></br>
  <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="#документация-api">Документация API</a></li>
    <li><a href="#дорожная-карта">Дорожная карта</a></li>
    <li><a href="#контакты">Контакты</a></li>
  </ol>
<!-- </details> -->


## О проекте

flusql — это высокопроизводительная встраиваемая SQL СУБД, разработанная на языке Rust с архитектурой wait-free. Система предназначена для приложений, требующих максимальной масштабируемости и минимальных задержек при работе с данными.

**Отличительные особенности flusql:**

* Wait-free архитектура: полное отсутствие блокировок при операциях чтения и записи
* MVCC (Multi-Version Concurrency Control): параллельное чтение без блокировок и изолированные транзакции без блокировок
* Полноценный WAL (Write-Ahead Log): гарантии сохранности данных
* Поддержка ACID транзакций: надежность и согласованность
* Кэширование с контрольными точками: периодическая синхронизация данных
* Семейство столбцов: каждый столбец хранится отдельно
* Оптимизация для аналитики: быстрые агрегатные операции
* Эффективное сжатие: повторяющиеся значения хранятся один раз
* Векторизованная обработка: пакетная обработка данных
* Колоночное хранение данных: оптимизировано для аналитических запросов
* Встроенная система Lua-плагинов: расширяемость функционала субд, через написанные на языке lua-плагины


<p align="right">(<a href="#readme-top">К началу</a>)</p>

## Глоссарий

* **База Данных(БД)** - это структурированное, организованное хранилище данных, которое позволяет удобно собирать, хранить, управлять и извлекать информацию.
* **Система Управления Базами Данных(СУБД)** - это программное обеспечение, которое позволяет создавать, управлять и взаимодействовать с базами данных
* **Мультимодельная СУБД** - это СУБД, которая объединяет в себе поддержку нескольких моделей данных (реляционной, документной, графовой, ключ-значение и др.) в рамках единого интегрированного ядра.
* **Резидентная СУБД** - это СУБД, которая работает непрерывно в оперативной памяти (RAM).
* **Инстанс** - это запущенный экземляр базы данных.
* **Узел (хост,нода,шард)** - это отдельный сервер (физический или виртуальный), который является частью кластера или распределенной системы и выполняет часть общей работы.
* **Слайс (от англ. "slice"-слой)** - это логический и физически изолированный фрагмент коллекции документов, полученный в результате горизонтального партиционирования (шардирования) и размещенный на определенном узле кластера с целью масштабирования производительности и объема данных.
* **Репликасет** - это группа серверов СУБД, объединенных в отказоустойчивую конфигурацию, где один узел выполняет роль первичного (принимающего операции записи), а один или несколько других - роль вторичных (синхронизирующих свои данные с первичным и обслуживающих чтение), с автоматическим переизбранием первичного узла в случае его сбоя.
* **Временные ряды (time series)** - это это упорядоченная во времени последовательность данных, собранная в регулярные промежутки времени из какого-либо источниика (цены на акции, данные температуры, объёмы продаж и.т.д.).
* **OLTP (Online Transactional Processing-Онлайн обработка транзакций)**- это технология обработки транзакций в режиме реального времени. Её основная задача заключается в обеспечении быстрого и надёжного выполнения операций, которые происходят ежесекундно в бизнесе. Они обеспечивают быстрое выполнение операций вставки, обновления и удаления данных, поддерживая целостность и надежность транзакций.
* **OLAP (Online Analytical Processing - Оперативная аналитическая обработка)** — это технология, которая работает с историческими массивами информации, извлекая из них закономерности и производя анализ больших объемов данных, поддерживает многоразмерные запросы и сложные аналитические операции. Данная технология оптимизирована для выполнения сложных запросов и предоставления сводной информации для принятия управленческих решений.
* **HTAP (Hybrid Transactional and Analytical Processing - Гибридная транзакционно-аналитическая обработка)**- это технология, которая заключаются в эффективном совмещении операционных и аналитических запросов, т.е. классов OLTP и OLAP.
* **Кластер** - это группа компьютеров, объединённых высокоскоростными каналами связи для решения сложных вычислительных задач и представляющая с точки зрения пользователя группу серверов, объединенных для работы как единая система.
* **WUI (от англ. Web-User-Interface "веб интерфейс пользователя")** - это термин проекта futriix, означающий веб-интерфейс (интерфейс работающий в веб-браузере)
* **Сервер-приложений (англ. application-server)** - это программное обеспечение, которое обеспечивает выполнение бизнес-логики и обработку запросов от клиентов (например, веб-браузеров или мобильных приложений). Он служит платформой для развертывания и управления приложениями, имея встроенные интепретаторы и/или компиляторы популярных языков программирования (php,go,python), что обеспечивает взаимодействие между пользователями, базами данных и другими системами.
* **REPL (от англ. read-eval-print loop — цикл "чтение — вычисление — вывод")** - это объединённые в одном приложении сервер и клиент для работы со встроенным приложением, применимо к данному проекту- к встроенной субд "futriix"
* **workflow (англ. workflow — «поток работы»)** — это принцип организации рабочих процессов, в соответствии с которым повторяющиеся задачи представлены как последовательность стандартных шагов.
* **wait-free (дословно с англ. wait-free — «свободный от ожидания»)**-класс неблокирующих алгоритмов, в которых каждая операция должна завершаться за конечное число шагов независимо от активности других потоков.
* **CA (англ. Certificate Authority - Центры Сертификации)** - это организации, которые выдают доверенные криптографические сертификаты.
* Команды, выполняемые с привилегиями суперпользователя (root), отмечены символом приглашения **«#»**
* Команды, выполняемые с правами обычного пользователя(user), отмечены символом приглашения **«$»**

<p align="right">(<a href="#readme-top">К началу</a>)</p>


## Лицензия

Проект распространяется под 2-пунктной лицензией BSD. Подробнсти в файле LICENSE.txt. Эта лицензия является одной из самых демократичных лицензий свободного программного обеспечения. Она позволяет использовать, изменять и распространять код в коммерческих целях без каких-либо ограничений, за исключением сохранения уведомления об авторских правах.

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

Все дополнительное программное обеспечение (включая модули на языке lua, тесты) предоставляются "как есть", без гарантий и обязательств со стороны разработчиков. Разработчики не несут ответственности за прямой или косвенный ущерб, вызванный использованием открытого кода Futriix и futriix или технических решений, использующих этот код.

<p align="right">(<a href="#readme-top">К началу</a>)</p>


## Системные требования

Данный раздел описывает системные требования, предъявляемые как к аппаратному, так и к программному обеспечению, на котором планируется запускать `flusql`

* Тип процессора: Intel 86x
* Разрядность процессора: 64-бит
* ОЗУ: от 4 Гб и выше
* Операционная система: **Linux Fedora** (**рекомендуемая**), Linux семейства Debian (Ubintu, Linux Mint, Linux MX)


> [!WARNING]  
> **Flusql может быть скомпилирован для следующих операционных систем: `OSX`, `Open Indiana`, `FreeBSD`, но сборка для этих операционных систем не проводилась!!!**
 
<p align="right">(<a href="#readme-top">К началу</a>)</p>



## Структура модулей

```txt
src/
├── core/           # Ядро СУБД
│   ├── database.rs # Управление базами данных
│   ├── table.rs    # Управление таблицами
│   ├── index.rs    # Индексы
│   └── column_family.rs # Колоночное хранение
├── parser/         # Парсер SQL
├── wal/           # Write-Ahead Log
├── mvcc/          # MVCC движок
├── lua/           # Lua интерпретатор
├── cli/           # Командный интерфейс
└── utils/         # Вспомогательные модули
```
 <p align="right">(<a href="#readme-top">К началу</a>)</p>


 ## Подготовка

**Для операционных систем семейства Debian** выполните следующие шаги:
* Обновляем индексы репозиториев (Без этой команды, установщик может не найти пакеты или использовать старые версии):

  ```sh
   # apt update
   ```
* Устанавливаем необходимые пакеты:

  ```sh
   # apt install curl build-essential git wget
   ```

* **Устанавливаем язык программирования Rust**
   ```sh
   # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```
 > [!WARNING]  
> **Если используя команду выше установить язык Rust не удалось, тогда устанавливаем язык Rust альтернативным способом, указанном ниже:**
```sh
$ sudo -s 
# apt update
# apt install rustup && rustup default stable
# rustup update
# rustc --version

**Если всё сделано правильно то в терминале должен появиться ответ: rustc 1.92.0 (ded5c06cf 2025-12-08)**

```

* **Для операционных систем семейства Red Hat (Fedora, Aurora)** выполните следующие шаги:
* Обновляем индексы репозиториев (Без этой команды, установщик может не найти пакеты или использовать старые версии):

  ```sh
   # dnf update
   ```

* Устанавливаем необходимые пакеты:

  ```sh
   # dnf install curl build-essential git wget
   ```

* **Устанавливаем язык программирования Rust**

   ```sh
   # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```
 
 
## Компиляция

```sh
# Клонирование репозитория
git clone https://github.com/yourusername/flusql.git
cd flusql

# Сборка в режиме релиза (оптимизированная)
cargo build --release

# Запуск тестов
cargo test
```

<p align="right">(<a href="#readme-top">К началу</a>)</p>


## Динамическая библиотека

По умолчанию, после компиляции в директории `/flusql/target/release` находится файл `libflusql.so`-это динамически подключаемая библиотека (shared object), созданная в процессе компиляции проекта flusql.


Для production сборки будет создана оптимизированная версия:

```sh
cargo build --release
```

После этой команды появится `/flusql/target/release/libflusql.so`:

  * Оптимизирован по размеру и скорости
  * Без отладочной информации
  * Готов к использованию в production-среде


**libflusql.so** — это скомпилированная библиотека flusql, которая может использоваться как самостоятельный компонент или подключаться к другим программам для расширения их функциональности SQL и Lua возможностями.


**Основное назначение**

**libflusql**-это скомпилированная версия Rust-библиотеки в формате динамической библиотеки для ОС семейства Linux:

   * .so — стандартное расширение для shared objects в Linux (аналог .dll в Windows)
   * Содержит откомпилированный код всех модулей проекта (кроме main.rs)
   * Может быть динамически загружена и использована другими программами

  **Отличие библиотеки от исполняемого файла**
  > [!IMPORTANT]  
  > flusql — самостоятельная программа (компилируется из src/main.rs)
  > libflusql.so — библиотека для использования в других программах
  


   Данная библиотека создаётся, благодаря указанной конфигурации в файле `Cargo.toml`, а именно строке: `crate-type = ["cdylib", "staticlib", "rlib"]`. Она означает, что компилятор создает несколько форматов:


    * cdylib → libflusql.so (динамическая библиотека для C-интерфейса)
    * staticlib → libflusql.a (статическая библиотека)
    * rlib → libflusql.rlib (Rust-специфичный формат для зависимостей)



 **Практическое использование**

1) Использование как библиотеки Lua

Так как flusql поддерживает Lua, libflusql.so может использоваться как:

    * Модуль Lua (через require в Lua)
    * Расширение для других программ, которые могут загружать динамические библиотеки


2) Интеграция с другими языками

Библиотека может быть использована из:

   * C/C++ программ (через C-совместимый интерфейс)
   * Python (через ctypes или cffi)
   * Node.js (через FFI)
   * Других языков с поддержкой загрузки .so файлов

3) Тестирование и отладка

Файл находится в target/debug, что означает:

    * Скомпилирован с отладочной информацией (debug = true)
    * Не оптимизирован для производительности
    * Содержит символы для отладки
    * Используется при запуске тестов (cargo test)

  В контексте flusql (SQL база данных с поддержкой Lua и кластеризации), libflusql.so может быть использована как:

  1) Встраиваемая СУБД в другие приложения
  2) Модуль для расширения функциональности существующих систем
  3) Основа для языковых биндингов (Python, Node.js и т.д.)
  4) Серверный компонент, который можно динамически загружать


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

**Запуск интерактивного интефейса**

```sh
$ ./flusql
```

**Пример сессии**

```sql
Добро пожаловать в flusql! Введите HELP для справки.

flusql> CREATE DATABASE testdb;
База данных 'testdb' создана

flusql> USE testdb;
Используется база данных 'testdb'

flusql> CREATE TABLE users (id INT, name TEXT, age INT);
Таблица 'users' создана

flusql> INSERT INTO users (id, name, age) VALUES (1, 'Alice', 30);
Запись вставлена с ID: 1

flusql> SELECT * FROM users;
Найдено 1 записей
id | name | age
---------------
1 | Alice | 30

flusql> lua-mode
Вход в Lua режим. Введите 'exit' для выхода

lua> print("Hello from Lua!")
Hello from Lua!
```
<p align="right">(<a href="#readme-top">К началу</a>)</p>

## Основные команды

**Управление базами данных**

```sql
CREATE DATABASE mydb;
USE mydb;
SHOW DATABASES;
DROP DATABASE mydb;
```

**Управление таблицами**
```sql
CREATE TABLE users (
    id INT PRIMARY KEY,
    name TEXT NOT NULL,
    age INT,
    email TEXT UNIQUE
);

ALTER TABLE users ADD COLUMN phone TEXT;
DROP TABLE users;
```

**Операции с данными**
```sql
-- Вставка
INSERT INTO users (id, name, age) VALUES (1, 'Алиса', 30);

-- Выборка
SELECT * FROM users WHERE age > 25 ORDER BY name LIMIT 10;

-- Обновление
UPDATE users SET age = 31 WHERE id = 1;

-- Удаление
DELETE FROM users WHERE age < 18;
```
<p align="right">(<a href="#readme-top">К началу</a>)</p>


## Поддерживаемые расширенные возможности SQL

 * JOIN операции: LEFT JOIN, INNER JOIN
 * Агрегатные функции: GROUP BY, ORDER BY
 * Ограничения: FOREIGN KEY, CHECK, UNIQUE
 * Индексы: создание и удаление индексов
 * Триггеры: BEFORE/AFTER INSERT/UPDATE/DELETE

 <p align="right">(<a href="#readme-top">К началу</a>)</p>


## Lua-интеграция

```sql
lua-mode  -- Вход в режим Lua
```

```lua
-- Выполнение SQL из Lua
local result = execute_sql("SELECT * FROM users")
print("Результат:", result)

-- Работа с данными
local data = query_data("SELECT name, age FROM users")
for i, row in ipairs(data) do
    print("Строка", i, ":", table.concat(row, ", "))
end
```

## Импорт и экспорт данных из/в субд

```sql
EXPORT users TO '/path/to/users.csv';
IMPORT INTO users FROM '/path/to/data.csv';
```

## Программное использование

```rust
use flusql::{Database, Config};

// Создание конфигурации
let config = Config::default();

// Создание базы данных
let mut db = Database::create("mydb", &config)?;

// Создание таблицы
use flusql::core::{TableSchema, ColumnSchema, DataType};

let schema = TableSchema {
    columns: vec![
        ColumnSchema {
            name: "id".to_string(),
            data_type: DataType::Integer,
            nullable: false,
            unique: true,
        },
        ColumnSchema {
            name: "name".to_string(),
            data_type: DataType::Text,
            nullable: false,
            unique: false,
        },
    ],
    primary_key: Some("id".to_string()),
    indexes: vec![],
    foreign_keys: vec![],
    checks: vec![],
};

db.create_table("users", schema)?;
```
<p align="right">(<a href="#readme-top">К началу</a>)</p>


## Тестирование

<p align="right">(<a href="#readme-top">К началу</a>)</p>


### Оптимизации

* Memory-mapped файлы: для WAL и больших таблиц
* Пакетная обработка: группировка операций записи
* Кэширование запросов: повторное использование планов выполнения
* Векторизованные операции: SIMD для агрегатных функций
    
## Конфигурация

**Файл конфигурации `config.toml`**

```sh
# Путь к директории с базами данных
data_dir = "./data"

# Максимальный размер лог-файла в MB
max_log_size_mb = 100

# Включить журналирование
enable_logging = true

# Автоматическое создание индексов
auto_index = true

# Размер страницы памяти в KB
page_size_kb = 4
```

## Переменные окружения

```sh
export FLUSQL_DATA_DIR="/var/lib/flusql"
export FLUSQL_LOG_LEVEL="info"
export FLUSQL_MAX_MEMORY="2GB"
```
<p align="right">(<a href="#readme-top">К началу</a>)</p>

## Сферы применения

**Бизнес-приложения**

*    Финансовые системы: обработка транзакций в реальном времени
*    Логистика и трекинг: отслеживание перемещений объектов
*   CRM системы: управление клиентской базой

**IoT и телеметрия**

  *   Сбор данных с датчиков: хранение временных рядов
  *  Аналитика в реальном времени: обработка потоковых данных
  *  Мониторинг систем: сбор и анализ метрик

**Игровая индустрия**

 *   Игровые профили: хранение данных игроков
 *   Аналитика игрового процесса: сбор статистики
 *   Социальные функции: чаты, друзья, достижения

**Научные исследования**

 *  Обработка экспериментальных данных: хранение и анализ
 *   Машинное обучение: подготовка обучающих выборок
 *   Статистический анализ: агрегация и обработка данных


**Мобильные приложения**

   * Локальное хранение: автономная работа приложения
   *  Синхронизация данных: фоновая обработка
   *  Кэширование: ускорение работы приложения

 <p align="right">(<a href="#readme-top">К началу</a>)</p> 
    
## Документация API

**Основные типы**

```rust
// База данных
pub struct Database;

// Таблица
pub struct Table;

// Схема таблицы
pub struct TableSchema;

// Значение данных
pub enum Value {
    Integer(i64),
    Text(String),
    Boolean(bool),
    Float(f64),
    Null,
}

// Парсер SQL
pub struct SqlParser;
```
<p align="right">(<a href="#readme-top">К началу</a>)</p>


**Обработка ошибок**

```rust
use flusql::{DatabaseError, TableError};

match result {
    Ok(data) => process_data(data),
    Err(DatabaseError::NotFound(name)) => {
        eprintln!("База данных '{}' не найдена", name);
    }
    Err(DatabaseError::IoError(e)) => {
        eprintln!("Ошибка ввода-вывода: {}", e);
    }
    Err(e) => {
        eprintln!("Неизвестная ошибка: {}", e);
    }
}
```

```sh
-- OLTP-операция: быстрая транзакция
Futriix_db.update("users", "user123", '{"balance": 100}')

-- OLAP-операция: аналитический запрос  
local analytics = Futriix_db.query("transactions", '{"date": {"$gt": "2024-01-01"}}')
```

<p align="right">(<a href="#readme-top">К началу</a>)</p>

<!-- ROADMAP -->
## Дорожная карта

- [x] Реализовать базовые операторы CRUD SQL на одном узле
- [x] Реализовать поддержку триггеров (обратных вызовов)
- [x] Реализовать поддержку многопоточности
- [x] Реализовать неблокирующие чтение/запись
- [x] Реализовать мульти-мастер асинхронную репликацию через файл конфигурации
- [x] Реализовать логирование
- [x] Реализовать поддержку синхронной мастер-мастер репликации
- [x] Реализовать поддержку кластеризации согласно паттерну "Centralized Coordinator"
- [x] Реализовать поддержку первичных индексов
- [x] Реализовать базовую поддержку транзакций
- [x] Реализовать поддержку первичных и вторичных индексов
- [ ] Добавить механизм сторонних плагинов, которые реализовываются на языке lua, расширяющих функционал субд 
- [x] Добавить в каждую таблицу временную метку-"timestamp" (текущую дату)
- [x] Заменить диалект SQL на диалект SQL-PostgreSQL
- [x] Переписать асинхронную мастер-мастер репликацию на синхронную мастер-мастер репликацию
- [ ] Реализовать поддержку базового (на нескольких узлах) языка SQL
- [ ] Реализовать графический веб-интерфейс для управления кластером
- [ ] Реализовать аппаратную поддержку платформы "RasberryPi"

См. [Открытые проблемы](https://source.futriix.ru/gvsafronov/futriixw/issues) полный список предлагаемых функций (и известных проблем).

<p align="right">(<a href="#readme-top">К началу</a>)</p>

<!-- CONTRIBUTING -->


<!-- CONTACT -->
## Контакты

Григорий Сафронов - [E-mail](gvsafronov@yandex.ru) 

<p align="right">(<a href="#readme-top">К началу</a>)</p>