diff --git a/README-NEW.md b/README-NEW.md new file mode 100644 index 0000000..ad1e5a2 --- /dev/null +++ b/README-NEW.md @@ -0,0 +1,489 @@ +############################################################# +# Полный список команд во встроенной СУБД futriix # +############################################################# + +#### Функции файлов + +```sh +futriix.wal - Write-Ahead Log файл СУБД: +``` + * Функция: Обеспечивает durability данных + * Содержит: Все операции записи перед их применением к основному хранилищу + * Назначение: Восстановление данных после сбоев + +```sh +wal.log - Лог операций Write-Ahead Log: +``` + * Функция: Дублирующий лог для отладки и мониторинга + * Содержит: Те же операции что и futriix.wal, но в читаемом формате + * Назначение: Анализ операций записи + +```sh +futriix.log - Основной лог субд: +``` + * Функция: Логирование работы всей СУБД + * Содержит: Информационные сообщения, ошибки, предупреждения + * Назначение: Мониторинг и отладка работы системы + + ```sh +history_with_timestamps - Файл лог сервера-приложений falcot +``` + + * Функция: Логирование работы всего сервера приложений + * Содержит: Введённые команды в сервере приложения, текущие дату и время (временную метку) + * Назначение: Мониторинг и отладка работы системы + +** Эти файлы создаются автоматически при выполнении операций записи в базу данных через Lua интерпретатор или HTTP API. + + +## Тестирование + +```sh +cargo test +``` +### Запуск только unit-тестов + ```sh +cargo test unit_test +``` +### Запуск конкретного unit-теста +```sh +cargo test test_storage_engine_unit +``` +### Запуск тестов с выводом +```sh +cargo test -- --nocapture +``` + +### Переход в режим базы данных +```sh +inbox.start +``` + +### Команды для заполнения WAL файла + +####Все команды CRUD должны логирироваться в WAL файл, который называется "futriix.wal", что обеспечивает durability данных. +#### Замечание: После выполнения любых команд CRUD - файл "futriix.wal" должен будет содержать записи всех выполненных операций, а именно: создания, изменения и удаления документа. +Создания, изменения и удаления пространства. + + +### Выход из режима базы данных +```sh +exit +``` + + +##Базовые команды + +### Выход из приложения +```sh +exit +``` + +### Переключение между режимами +```sh +inbox.start # Переход в режим базы данных +exit # Возврат в режим Lua из режима базы данных а также выход из режима Lua и возврат в терминал операционной системы +``` + +### Команды CRUD операций + +### Создание пространства (синоним термина "база данных") +```sh +create.space users +``` + + +### Удаление простраства (синоним термина "база данных") +```sh +delete.space +``` + +### Создание документа (синоним термина "коллекция") +```sh +create +create users user1 '{"name": "John", "age": 30}' +create products prod1 '{"title": "Laptop", "price": 999.99}' +``` + +### Чтение документа +```sh +read +read users user1 +read products prod1 +``` + +### Изменение (синоним термина "обновление") документа +```sh +update +update users user1 '{"name": "John Doe", "age": 31}' +``` + +### Удаление документа +```sh +delete +delete users user1 +``` + +### Создание кортежа (синоним термина "вложенного документа в документ") +```sh +create.tuple +create.tuple users profile1 '{"type": "user_profile", "premium": true}' +``` + +### Чтение кортежа (синоним термина "вложенного документа в документ") +```sh +read.tuple +read.tuple users profile1 '{"type": "user_profile", "premium": true}' +``` + +### Удаление кортежа (синоним термина "вложенного документа в документ") +```sh +delete.tuple +delete.tuple users profile1 '{"type": "user_profile", "premium": true}' +``` + +### Создание кортежей в пространстве +```sh +create.tuple users tuple1 '{"type": "profile", "data": {"premium": true, "settings": {"theme": "dark"}}}' +``` + +### Удаление кортежей в пространстве +```sh +delete.tuple users tuple1 +``` + +##Команды для работы с индексами + + +### Типы индексов: + * hash : для точных поисков + * timeindex : для диапазонных запросов + * fulltext: для полнотекстового поиска + * spatial : для пространственных данных + +### Создание первичного индекса +```sh +create.primary.index +create.primary.index users +create.primary.index products +``` + +### Поиск по всем индексам или по конкретному индексу +```sh +search.all.index +search.secondary.index +``` + +### Удаление первичного индекса +```sh +create.primary.index +create.primary.index users +create.primary.index products +``` + +### Создание вторичного индекса +```sh +create.secondary.index +create.secondary.index users email hash +create.secondary.index users age btree +create.secondary.index users name fulltext +create.secondary.index locations coordinates spatial +``` + +### Удаление вторичного индекса +```sh +drop.primary.index +drop.primary.index users +create.primary.index products +``` + +### Удаление всех индексов, которые созданы на данный момент в субд +```sh +drop.all.index +``` + +### Импорт находящихся данных в субд из файла в формате ".csv" +```sh +futriiX:~> mode.csv +futriiX(csv-mode): import /path/to/your/file.csv +file.csv sucessfully loaded +futriiX(csv-mode): exit +futriiX:~> +``` + +### Экспорт находящихся данных в субд в файл в формате ".csv" +```sh +futriiX:~> mode.csv +futriiX(csv-mode): export /path/to/your/file.csv +file.csv sucessfully unloaded +futriiX(csv-mode): exit +futriiX:~> +``` + +## Команды по работе с кластером + +### Статус кластера (собран кластер в данный момент или нет) +```sh +status +cluster.status +``` + + +### Команды Raft кластера +```sh +## Добавление узла +add.node +add.node http://raft1.example.com:9080 +``` + +### Удаление узла из кластера +```sh +remove.node +remove.node node123 +``` + +### Список raft.узлов (данная команда отображает узлы, которые объеденены протоколом raft и их текущую роль (leader or follower)) +```sh +list.raft.nodes +``` + +### Настройка пользователей и прав + +```sh +# Создание пользователя с полными правами +lua> add_user("admin", {can_read = true, can_write = true, can_create = true, can_delete = true, allowed_collections = {}}) + +# Создание пользователя только для чтения определенных коллекций +lua> add_user("analyst", {can_read = true, can_write = false, can_create = false, can_delete = false, allowed_collections = {"sales", "reports"}}) + +# Создание редактора с ограниченными правами +lua> add_user("editor", {can_read = true, can_write = true, can_create = true, can_delete = false, allowed_collections = {"articles", "comments"}}) +``` + +### Проверка прав доступа + +```sh + +# Проверка прав чтения +lua> can_read("analyst", "sales") +true + +lua> can_read("analyst", "users") +false + +# Проверка прав записи +lua> can_write("editor", "articles") +true + +lua> can_write("editor", "users") +false + +# Проверка прав создания +lua> can_create("editor", "articles") +true + +# Проверка прав удаления +lua> can_delete("editor", "articles") +false +``` + +### Практические сценарии с ACL + +```sh +# Инициализация системы прав +lua> function init_acl() +>> add_user("admin", {can_read = true, can_write = true, can_create = true, can_delete = true, allowed_collections = {}}) +>> add_user("manager", {can_read = true, can_write = true, can_create = true, can_delete = false, allowed_collections = {"orders", "customers"}}) +>> add_user("viewer", {can_read = true, can_write = false, can_create = false, can_delete = false, allowed_collections = {"products"}}) +>> end +lua> init_acl() + +# Безопасное создание документа с проверкой прав +lua> function secure_create(user, collection, key, value) +>> if not can_create(user, collection) then return "Access denied" end +>> return insert(collection, key, value) +>> end + +lua> secure_create("manager", "orders", "order_001", {customer = "john", amount = 100}) +Document inserted + +lua> secure_create("viewer", "orders", "order_002", {customer = "jane", amount = 200}) +Access denied +``` + +### Базовые операции с транзакциями + +```sh +# Начало транзакции +lua> begin("tx_order_001") + +# Добавление операций в транзакцию +lua> add_operation("tx_order_001", {operation = "create", collection = "orders", key = "order_001", value = {customer_id = "cust_123", total = 150.75, status = "pending"}}) + +lua> add_operation("tx_order_001", {operation = "update", collection = "customers", key = "cust_123", value = {last_order = "order_001", total_spent = 1200.50}}) + +lua> add_operation("tx_order_001", {operation = "create", collection = "payments", key = "pay_001", value = {order_id = "order_001", amount = 150.75, status = "processed"}}) + +# Фиксация транзакции +lua> commit("tx_order_001") +``` + +### Пример №1 перевод средств между счетами +```sh + +# Функция перевода средств +lua> function transfer_funds(from_acc, to_acc, amount) +>> local tx_id = "tx_transfer_" .. os.time() +>> begin(tx_id) +>> +>> local from_balance = get("accounts", from_acc).balance +>> if from_balance < amount then +>> rollback(tx_id) +>> return "Insufficient funds" +>> end +>> +>> add_operation(tx_id, {operation = "update", collection = "accounts", key = from_acc, value = {balance = from_balance - amount}}) +>> +>> local to_balance = get("accounts", to_acc).balance +>> add_operation(tx_id, {operation = "update", collection = "accounts", key = to_acc, value = {balance = to_balance + amount}}) +>> +>> add_operation(tx_id, {operation = "create", collection = "transactions", key = "tx_" .. os.time(), value = {from = from_acc, to = to_acc, amount = amount, date = os.date()}}) +>> +>> return commit(tx_id) +>> end + +# Использование функции перевода +lua> transfer_funds("acc_001", "acc_002", 500.00) +``` +###Пример №2 Создание заказа с резервированием товаров + +```sh +# Комплексная транзакция создания заказа +lua> begin("tx_complete_order_789") + +# 1. Создание заказа +lua> add_operation("tx_complete_order_789", {operation = "create", collection = "orders", key = "order_789", value = {customer = "john_doe", items = {{product = "prod_1", qty = 2}, {product = "prod_2", qty = 1}}, total = 299.99, status = "created"}}) + +# 2. Обновление инвентаря +lua> add_operation("tx_complete_order_789", {operation = "update", collection = "inventory", key = "prod_1", value = {quantity = get("inventory", "prod_1").quantity - 2}}) + +lua> add_operation("tx_complete_order_789", {operation = "update", collection = "inventory", key = "prod_2", value = {quantity = get("inventory", "prod_2").quantity - 1}}) + +# 3. Обновление клиента +lua> add_operation("tx_complete_order_789", {operation = "update", collection = "customers", key = "john_doe", value = {order_count = get("customers", "john_doe").order_count + 1, total_spent = get("customers", "john_doe").total_spent + 299.99}}) + +# Фиксация +lua> commit("tx_complete_order_789") +``` + +###Пример №3 Обработка ошибок и откат + +```sh +# Транзакция с проверкой и откатом при ошибке +lua> begin("tx_safe_update") + +lua> add_operation("tx_safe_update", {operation = "update", collection = "products", key = "prod_1", value = {price = 99.99}}) + +# Проверяем условие перед коммитом +lua> if get("products", "prod_1").stock < 0 then +>> print("Negative stock detected, rolling back") +>> rollback("tx_safe_update") +>> else +>> commit("tx_safe_update") +>> end +``` + +###Пимер №4 Комбинированные примеры: ACL + транзакции + +```sh +# Безопасная бизнес-функция +lua> function secure_business_operation(user, operation_data) +>> -- Проверка прав +>> if not can_create(user, "orders") then return "No order creation permission" end +>> if not can_update(user, "inventory") then return "No inventory update permission" end +>> +>> -- Начало транзакции +>> local tx_id = "tx_secure_" .. os.time() +>> begin(tx_id) +>> +>> -- Операции +>> add_operation(tx_id, {operation = "create", collection = "orders", key = operation_data.order_id, value = operation_data.order}) +>> add_operation(tx_id, {operation = "update", collection = "inventory", key = operation_data.product_id, value = {stock = get("inventory", operation_data.product_id).stock - operation_data.quantity}}) +>> +>> -- Фиксация +>> return commit(tx_id) +>> end + +# Использование +lua> secure_business_operation("manager", {order_id = "order_999", order = {customer = "alice", total = 150}, product_id = "prod_5", quantity = 3}) +``` + +###Пример №5 Управление транзакциями + +```sh +# Просмотр статуса транзакций (если такая функция реализована) +lua> function shows() +>> -- В реальной реализации здесь был бы вызов метода для получения списка транзакций +>> print("Active transactions management") +>> end + +# Откат транзакции при таймауте +lua> function timeout_rollback(tx_id, timeout_seconds) +>> local start_time = os.time() +>> while os.time() - start_time < timeout_seconds do +>> -- Ждем завершения +>> end +>> rollback(tx_id) +>> return "Transaction rolled back due to timeout" +>> end +``` + +###Пример №4 Практические команды для повседневного использования + +```sh +# Быстрое создание пользователя с правами +lua> add_user("api_user", {can_read = true, can_write = true, can_create = true, can_delete = false, allowed_collections = {"sessions", "cache"}}) + +# Простая транзакция обновления +lua> begin("tx_quick_update") +lua> add_operation("tx_quick_update", {operation = "update", collection = "config", key = "app_settings", value = {version = "1.2.3", updated_at = os.date()}}) +lua> commit("tx_quick_update") + +# Проверка системы перед операциями +lua> can_read("current_user", "target_collection") and "Access granted" or "Access denied" +``` + +### Пример создания пользователя с зашифрованным паролем, с помощью алгоритма шифрования MD-5 + +```sh +-- 1. Создаем пространство +lua> create_space("users") + +-- 2. Создаем процедуры +lua> create_procedure("create_user", 'function create_user(username, password, user_data) return create_user_with_password("users", username, password, user_data) end') + +lua> create_procedure("authenticate_user", 'function authenticate_user(username, password) local success, message = verify_user_password("users", username, password) return {success = success, message = message} end') + +-- 3. Создаем пользователя +lua> call_procedure("create_user", '["alice", "password123", {"name": "Alice", "role": "user"}]') +Command executed successfully + +-- 4. Проверяем аутентификацию +lua> local result = call_procedure("authenticate_user", '["alice", "password123"]') +lua> print(result) +{success = true, message = "Password correct"} + +-- 5. Проверяем неправильный пароль +lua> local wrong_result = call_procedure("authenticate_user", '["alice", "wrongpass"]') +lua> print(wrong_result) +{success = false, message = "Password incorrect"} +``` + + + + +(i to the second power) + + + +