Manual del Programador

Guía de referencia completa y manual de integración para JsonDB Fluxer Fast (Rust)
Versión 0.1.1 Rust Edition 2021 Crates.io

1. Introducción

JsonDB Fluxer Fast es un motor de base de datos embebido en memoria de documentos JSON con persistencia asíncrona a disco e intérprete de consultas SQL nativo escrito en Rust.

Ofrece escrituras atómicas garantizadas a través de reemplazo de archivos temporales (`.tmp`), concurrencia segura con DashMap, y ejecución de SQL con soporte para INNER JOIN, GROUP BY, HAVING, agregaciones y visualización en tablas estilo consola.

2. Cómo iniciar un nuevo proyecto

Para comenzar a utilizar la librería, primero crea un nuevo proyecto ejecutable de Rust con Cargo en tu terminal:

cargo new mi_proyecto_db
cd mi_proyecto_db

3. Instalación de Dependencias

Una vez creado y estando dentro de la carpeta de tu proyecto de Rust, añade JsonDB Fluxer Fast ejecutando en tu terminal:

cargo add jsondb_fluxer_fast tokio serde serde_json

O agrégalas manualmente en el archivo Cargo.toml generado en tu proyecto:

[dependencies]
jsondb_fluxer_fast = "0.2.1"
tokio = { version = "1.38", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

4. Referencia de Métodos de la Librería

open()

pub async fn open<P: AsRef<Path>>(base_dir: P, db_name: &str) -> Result<Self>

Abre o crea la base de datos en el directorio base especificado. Carga automáticamente los datos existentes en memoria.

use jsondb_fluxer_fast::JsonDB;

#[tokio::main]
async fn main() -> jsondb_fluxer_fast::Result<()> {
    let db = JsonDB::open("./data_db", "mi_sistema").await?;
    println!("Base de datos abierta correctamente");
    Ok(())
}

insert()

pub async fn insert<T: Serialize>(&self, table: &str, id: &str, record: &T) -> Result<()>

Inserta o reemplaza un registro en la tabla especificada identificado por su id.

use serde::Serialize;

#[derive(Serialize)]
struct Producto {
    nombre: String,
    precio: f64,
}

let prod = Producto { nombre: "Laptop Pro".to_string(), precio: 1200.00 };
db.insert("productos", "prod_101", &prod).await?;

get()

pub fn get<T: DeserializeOwned>(&self, table: &str, id: &str) -> Result<Option<T>>

Obtiene un registro por su ID deserializándolo en el struct deseado.

use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Producto {
    nombre: String,
    precio: f64,
}

if let Some(prod) = db.get::("productos", "prod_101")? {
    println!("Encontrado: {} (${})", prod.nombre, prod.precio);
}

get_all()

pub fn get_all<T: DeserializeOwned>(&self, table: &str) -> Result<Vec<T>>

Retorna un vector con todos los registros pertenecientes a una tabla.

let todos: Vec = db.get_all("productos")?;
println!("Total de productos: {}", todos.len());

find_where()

pub fn find_where<T: DeserializeOwned>(&self, table: &str, query: &QueryOptions) -> Result<Vec<T>>

Ejecuta una consulta mediante la API de programación fluida con filtros, ordenamiento y límites.

use jsondb_fluxer_fast::{QueryOptions, Condition, Operator, OrderBy, OrderDirection};

let query = QueryOptions::new()
    .filter(Condition::new("precio", Operator::GreaterThanOrEqual, 500.0))
    .order_by(OrderBy::new("precio", OrderDirection::Desc))
    .limit(5);

let filtrados: Vec = db.find_where("productos", &query)?;

query_sql()

pub fn query_sql<T: DeserializeOwned>(&self, sql: &str) -> Result<Vec<T>>

Ejecuta una consulta SQL en formato cadena devolviendo resultados mapeados a un struct fuertemente tipado.

let items: Vec = db.query_sql("SELECT * FROM productos WHERE precio > 100")?;

query_sql_json()

pub fn query_sql_json(&self, sql: &str) -> Result<Vec<serde_json::Value>>

Ejecuta consultas SQL nativas (con soporte para INNER JOIN, GROUP BY, HAVING, agregaciones y CASE WHEN) devolviendo un vector de valores JSON genéricos.

let sql = "SELECT categoría, AVG(precio) FROM productos GROUP BY categoría HAVING avg_precio > 200";
let res = db.query_sql_json(sql)?;
JsonDB::print_table(&res);

update_fields()

pub async fn update_fields(&self, table: &str, id: &str, updates: &serde_json::Map<String, Value>) -> Result<bool>

Actualiza parcialmente atributos específicos de un registro sin sobreescribir los demás campos.

use serde_json::json;

let mut cambios = serde_json::Map::new();
cambios.insert("precio".to_string(), json!(999.99));

let actualizado = db.update_fields("productos", "prod_101", &cambios).await?;

delete()

pub async fn delete(&self, table: &str, id: &str) -> Result<bool>

Elimina un registro de la tabla por su ID.

let eliminado = db.delete("productos", "prod_101").await?;

sync() / is_dirty()

pub fn is_dirty(&self) -> bool
pub async fn sync(&self) -> Result<()>

is_dirty() verifica si existen datos en memoria no guardados en disco. sync() fuerza la escritura a disco.

if db.is_dirty() {
    db.sync().await?;
    println!("Datos guardados a disco.");
}

set_flush_strategy()

pub async fn set_flush_strategy(&self, strategy: FlushStrategy)

Define la estrategia de guardado: FlushStrategy::Immediate (guardado automático al momento) o FlushStrategy::Manual (guardado en lote con sync()).

use jsondb_fluxer_fast::FlushStrategy;

db.set_flush_strategy(FlushStrategy::Manual).await;

create_table()

pub async fn create_table(&self, table: &str) -> Result<bool>

Crea explícitamente una nueva tabla/colección en la base de datos (equivalente a CREATE TABLE).

let creada = db.create_table("clientes").await?;
println!("Tabla creada: {}", creada);

drop_table()

pub async fn drop_table(&self, table: &str) -> Result<bool>

Elimina completamente una tabla/colección de la base de datos y memoria (equivalente a DROP TABLE).

let eliminada = db.drop_table("clientes").await?;
println!("Tabla eliminada: {}", eliminada);

drop_database()

pub async fn drop_database(&self) -> Result<()>

Elimina la base de datos completa limpiando la memoria y borrando su archivo físico en disco (equivalente a DROP DATABASE).

db.drop_database().await?;
println!("Base de datos eliminada por completo.");

alter_table()

pub async fn alter_table(&self, old_name: &str, new_name: &str) -> Result<bool>

Renombra una tabla/colección existente (equivalente a ALTER TABLE RENAME TO).

let renombrada = db.alter_table("clientes", "clientes_activos").await?;
println!("Tabla renombrada: {}", renombrada);

print_table()

pub fn print_table(rows: &[serde_json::Value])

Imprime un vector de JSONs en formato de tabla alineada formateada estilo consola.

let resultados = db.query_sql_json("SELECT * FROM productos")?;
JsonDB::print_table(&resultados);

5. Ejemplo Completo End-to-End

A continuación se presenta un programa ejecutable completo que integra todos los aspectos de la librería:

use jsondb_fluxer_fast::{JsonDB, FlushStrategy, Result};
use serde::{Deserialize, Serialize};
use serde_json::json;

#[derive(Serialize, Deserialize, Debug)]
struct Empleado {
    id: String,
    nombre: String,
    departamento: String,
    salario: f64,
}

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Abrir Base de Datos
    let db = JsonDB::open("./data_empresa", "recursos_humanos").await?;
    db.set_flush_strategy(FlushStrategy::Immediate).await;

    // 2. Insertar Empleados
    let emp1 = Empleado { id: "e1".into(), nombre: "Ana Gomez".into(), departamento: "TI".into(), salario: 3500.0 };
    let emp2 = Empleado { id: "e2".into(), nombre: "Carlos Ruiz".into(), departamento: "TI".into(), salario: 4200.0 };
    let emp3 = Empleado { id: "e3".into(), nombre: "Elena Sanz".into(), departamento: "Ventas".into(), salario: 2800.0 };

    db.insert("empleados", &emp1.id, &emp1).await?;
    db.insert("empleados", &emp2.id, &emp2).await?;
    db.insert("empleados", &emp3.id, &emp3).await?;

    println!("--- TODOS LOS EMPLEADOS ---");
    let todos = db.query_sql_json("SELECT * FROM empleados")?;
    JsonDB::print_table(&todos);

    // 3. Consulta Agregada con GROUP BY y HAVING
    println!("\n--- PROMEDIO SALARIAL POR DEPARTAMENTO ---");
    let sql_agg = "SELECT departamento, AVG(salario), COUNT FROM empleados GROUP BY departamento HAVING count >= 1";
    let agg_res = db.query_sql_json(sql_agg)?;
    JsonDB::print_table(&agg_res);

    // 4. Actualización Parcial
    println!("\n--- ACTUALIZANDO SALARIO DE ANA ---");
    let mut cambios = serde_json::Map::new();
    cambios.insert("salario".into(), json!(3900.0));
    db.update_fields("empleados", "e1", &cambios).await?;

    // 5. Verificar Cambio
    if let Some(emp) = db.get::("empleados", "e1")? {
        println!("Nuevo salario de Ana: ${}", emp.salario);
    }

    Ok(())
}

6. Referencia SQL y Ejemplos por Sentencia

El motor SQL nativo de JsonDB Fluxer Fast analiza y ejecuta sintaxis SQL estándar directamente sobre las colecciones de documentos JSON. A continuación se presentan ejemplos de código en Rust para cada sentencia soportada:

6.1. SELECT ... FROM

Selecciona todos los campos (*) o campos específicos de una colección/tabla JSON.

// Seleccionar todos los documentos de la tabla "usuarios"
let sql_all = "SELECT * FROM usuarios";
let res_all = db.query_sql_json(sql_all)?;
JsonDB::print_table(&res_all);

// Seleccionar campos específicos
let sql_fields = "SELECT nombre, edad FROM usuarios";
let res_fields = db.query_sql_json(sql_fields)?;
JsonDB::print_table(&res_fields);

6.2. WHERE (Filtros y Operadores)

Filtra documentos evaluando condiciones lógicas. Soporta operadores numéricos y de cadena: =, !=, >, <, >=, <=, LIKE y IN.

// Filtro por comparación numérica (edad >= 18)
let res1 = db.query_sql_json("SELECT * FROM usuarios WHERE edad >= 18")?;

// Filtro de coincidencia de patrones con LIKE
let res2 = db.query_sql_json("SELECT * FROM usuarios WHERE nombre LIKE '%Perez%'")?;

// Filtro por lista de valores permitidos con IN
let res3 = db.query_sql_json("SELECT * FROM usuarios WHERE estado IN ('activo', 'pendiente')")?;

6.3. INNER JOIN (Simple y Múltiple)

Combina dos o más colecciones mediante claves de relación comunes (soporta encadenamiento ilimitado de múltiples INNER JOIN):

// JOIN simple entre 2 tablas
let sql_join = "SELECT * FROM facturas INNER JOIN clientes ON facturas.cliente_id = clientes.id";
let res_join = db.query_sql_json(sql_join)?;
JsonDB::print_table(&res_join);

// Múltiples JOINs encadenados (3 tablas)
let sql_multi = r#"
    SELECT * FROM pedidos 
    INNER JOIN usuarios ON pedidos.usuario_id = usuarios.id 
    INNER JOIN productos ON pedidos.producto_id = productos.id
"#;
let res_multi = db.query_sql_json(sql_multi)?;
JsonDB::print_table(&res_multi);

6.4. CASE WHEN ... THEN ... ELSE ... END

Evalúa condiciones condicionales por cada documento y asigna un nuevo atributo derivado con un alias.

let sql_case = r#"
    SELECT nombre, nota,
    CASE WHEN nota >= 5 THEN 'Aprobado' ELSE 'Reprobado' END AS estado
    FROM alumnos
"#;

let res_case = db.query_sql_json(sql_case)?;
JsonDB::print_table(&res_case);

6.5. Funciones de Agregación (COUNT, SUM, AVG, MIN, MAX)

Calcula métricas agregadas globales sobre el conjunto de documentos filtrados.

// Conteo total de registros
let count_res = db.query_sql_json("SELECT COUNT FROM ventas")?;

// Promedio de un campo numérico
let avg_res = db.query_sql_json("SELECT AVG(monto) FROM ventas")?;

// Suma total, valor mínimo y máximo
let agg_res = db.query_sql_json("SELECT SUM(monto), MIN(monto), MAX(monto) FROM ventas")?;
JsonDB::print_table(&agg_res);

6.6. GROUP BY y HAVING

Agrupa documentos por el valor de una clave especificada y permite filtrar los grupos resultantes mediante la cláusula HAVING.

let sql_group = r#"
    SELECT categoria, AVG(precio), COUNT 
    FROM productos 
    GROUP BY categoria 
    HAVING count >= 2
"#;

let res_group = db.query_sql_json(sql_group)?;
JsonDB::print_table(&res_group);

6.7. ORDER BY, LIMIT y OFFSET (Paginación)

Ordena el resultado por una clave de forma ascendente (ASC) o descendente (DESC) y limita la cantidad de registros devueltos para paginación.

// Obtener la página 2 (registros 11 al 20) ordenada por salario descendente
let sql_page = "SELECT * FROM empleados ORDER BY salario DESC LIMIT 10 OFFSET 10";
let res_page = db.query_sql_json(sql_page)?;
JsonDB::print_table(&res_page);

6.8. Sentencias DDL (CREATE DATABASE, CREATE TABLE, ALTER TABLE, DROP TABLE, DROP DATABASE)

Permite administrar la base de datos y la estructura de colecciones utilizando sentencias DDL nativas en SQL:

// Crear/Inicializar una base de datos vía SQL
let res_db_create = db.query_sql_json("CREATE DATABASE tienda_online")?;

// Crear una nueva tabla explícitamente vía SQL
let res_create = db.query_sql_json("CREATE TABLE productos")?;

// Renombrar una tabla existente vía SQL
let res_alter = db.query_sql_json("ALTER TABLE productos RENAME TO inventario")?;

// Eliminar una tabla completa vía SQL
let res_drop = db.query_sql_json("DROP TABLE inventario")?;

// Eliminar la base de datos completa y su archivo en disco vía SQL
let res_db_drop = db.query_sql_json("DROP DATABASE")?;

6.9. Sentencias DML (INSERT INTO, UPDATE, DELETE FROM)

Permite la modificación directa de registros y colecciones ejecutando comandos DML mediante consultas SQL:

// Insertar un nuevo documento vía SQL
let res_ins = db.query_sql_json("INSERT INTO usuarios (id, nombre, email) VALUES ('10', 'Carlos Gomez', 'carlos@example.com')")?;

// Actualizar registros existentes vía SQL
let res_upd = db.query_sql_json("UPDATE usuarios SET nombre = 'Carlos G.' WHERE id = '10'")?;

// Eliminar registros vía SQL
let res_del = db.query_sql_json("DELETE FROM usuarios WHERE id = '10'")?;

7. Características SQL No Soportadas Aún

Al ser un motor incrustado orientado a documentos JSON con ejecuciones en memoria, JsonDB Fluxer Fast no soporta actualmente las siguientes características de bases de datos relacionales tradicionales RDBMS:

Característica SQL Estado Actual Alternativa en JsonDB
LEFT / RIGHT / FULL OUTER JOIN No Soportado Actualmente solo se soporta INNER JOIN. Para combinaciones no coincidentes se pueden consultar ambas colecciones y fusionar los datos en código Rust.
Subconsultas (Subqueries) No Soportado No se permiten consultas anidadas del tipo WHERE id IN (SELECT ...). Se debe ejecutar primero la subconsulta y pasar el resultado.
Transacciones (BEGIN / COMMIT / ROLLBACK) No Soportado Las escrituras son atómicas a nivel de archivo/documento mediante archivos .tmp, pero no existe un control de transacciones de múltiples pasos ACID relacionales.