Guía de referencia completa y manual de integración para JsonDB Fluxer Fast (Rust)
Versión 0.1.1Rust Edition 2021Crates.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"
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(())
}
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);
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?;
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")?;
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.