📚 Documentación OxideDB
Base de Datos OLAP de Alto Rendimiento en Rust
🚀 Inicio Rápido
OxideDB v1.6.0 - 5x más rápido que DuckDB en queries S3
Compatible con PostgreSQL Wire Protocol - usa psql, DBeaver, DataGrip
✨ Nuevo: Query Cache, Cursores para Streaming, ACID Transactions, Secondary Indexes
Instalación
# Descargar el binario
wget https://github.com/your-repo/oxidedb/releases/download/v1.6.0/oxidedb-server
# Dar permisos y mover
chmod +x oxidedb-server
sudo mv oxidedb-server /usr/local/bin/
# Verificar
oxidedb-server --versionConectar con psql (PostgreSQL)
# Iniciar servidor (puerto 5433 por defecto)
oxidedb-server --port 5433 --data-dir ./data
# Conectar con psql estándar
psql -h localhost -p 5433 -U oxide -d oxidedb
# Primera consulta
oxidedb=> SELECT 'Hello OxideDB!' as mensaje;
mensaje
---------------
Hello OxideDB!
(1 row)🐘 PostgreSQL Wire Protocol
Compatibilidad Total
OxideDB implementa el protocolo PostgreSQL v3. Conecta con cualquier cliente PostgreSQL:
CLI
psql, pgcli
IDEs
DBeaver, DataGrip, pgAdmin
Drivers
psycopg2, node-postgres, JDBC
# Conexión básica
psql -h your-server -p 5433 -U oxide -d oxidedb
# Con password (variable de entorno)
PGPASSWORD='your-password' psql -h server -p 5433 -U oxide -d oxidedb
# Ejecutar query directa
psql -h server -p 5433 -U oxide -d oxidedb -c "SELECT COUNT(*) FROM my_table;"
# Desde Python
import psycopg2
conn = psycopg2.connect(host="server", port=5433, user="oxide", dbname="oxidedb")☁️ S3 y Delta Lake
Queries directas sobre S3
OxideDB puede leer Parquet directamente desde S3 sin copiar datos:
-- Registrar tabla desde S3 (Parquet)
REGISTER PARQUET 's3://my-bucket/data/*.parquet' AS ventas;
-- Query directa - 5x más rápido que DuckDB
SELECT region, COUNT(*) as total, SUM(monto) as revenue
FROM ventas
WHERE fecha >= '2024-01-01'
GROUP BY region
ORDER BY revenue DESC;
-- 1.9M rows en 0.75 segundos desde S3Delta Lake con Time Travel
-- Registrar tabla Delta Lake
REGISTER DELTA 's3://my-bucket/delta/sales' AS sales_delta;
-- Query normal
SELECT * FROM sales_delta WHERE amount > 1000;
-- Time Travel: consultar versión anterior
SELECT * FROM sales_delta VERSION AS OF 5;
-- Ver historial de versiones
DELTA HISTORY sales_delta;AWS Glue Catalog Integration
# Iniciar con Glue Catalog
oxidedb-server --port 5433 \
--enable-glue-catalog \
--aws-region us-east-2
# Las tablas del Glue Catalog se descubren automáticamente
psql> \dt
List of relations
Schema | Name | Type
--------+---------------+-------
public | sales | table
public | customers | table
public | orders | table📊 SQL y Consultas OLAP
Sintaxis SQL Completa
OxideDB soporta SQL estándar con extensiones OLAP:
-- Funciones de ventana
SELECT
region,
ventas,
LAG(ventas, 1) OVER (ORDER BY fecha) as ventas_anterior,
RANK() OVER (PARTITION BY region ORDER BY ventas DESC) as ranking
FROM ventas_tabla;
-- Operaciones ROLLUP y CUBE
SELECT
region,
producto,
SUM(ventas) as total
FROM ventas_tabla
GROUP BY ROLLUP(region, producto); -- Subtotales jerárquicos
SELECT
region,
producto,
SUM(ventas) as total
FROM ventas_tabla
GROUP BY CUBE(region, producto); -- Todas las combinaciones
-- Agregaciones complejas con SIMD
SELECT
region,
COUNT(*) as transacciones,
SUM(monto) as total_ventas,
AVG(monto) as promedio,
PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY monto) as mediana
FROM transacciones
GROUP BY region
HAVING SUM(monto) > 100000;Tipos de Datos Soportados
-- Tipos numéricos (optimizados con SIMD)
INT, BIGINT, FLOAT, DOUBLE, DECIMAL(p,s)
-- Tipos texto
VARCHAR, TEXT, CHAR(n)
-- Tipos temporales
DATE, TIMESTAMP, TIME, INTERVAL
-- Tipos complejos
ARRAY, JSON (próximamente)📥 Query Cache y Streaming
OxideDB protege automáticamente contra queries que retornan millones de filas
Auto-LIMIT 500, LIMIT ALL para exportar, y Cursores para streaming eficiente
Auto-LIMIT: Protección contra OOM
Por defecto, OxideDB limita a 500 filas para evitar saturar memoria del cliente:
-- Query normal: máximo 500 filas (auto-limit)
SELECT * FROM ventas WHERE fecha >= '2024-01-01';
-- ⚠️ AUTO-LIMIT: Added LIMIT 500
-- Con LIMIT explícito: respeta tu límite
SELECT * FROM ventas WHERE fecha >= '2024-01-01' LIMIT 100;
-- Retorna 100 filas
-- Para exportar TODO: usa LIMIT ALL
SELECT * FROM ventas WHERE fecha >= '2024-01-01' LIMIT ALL;
-- 📤 EXPORT MODE: Retorna todas las filas (624,460 rows)Query Cache Inteligente
Cache LRU con TTL diferenciado para queries locales y S3:
-- Ver estadísticas del cache
SHOW CACHE;
-- metric | value
-- -----------------+-----------
-- hits | 1523
-- misses | 234
-- hit_rate | 86.7%
-- current_entries | 45
-- memory_bytes | 12458 KB
-- Invalidar cache de una tabla específica
REFRESH TABLE ventas;
-- ✅ Cache invalidado para 'ventas'
-- Limpiar todo el cache
CLEAR CACHE;Cursores para Streaming (Datasets Grandes)
Para exportar millones de filas sin saturar memoria, usa cursores:
-- 1. Declarar cursor (ejecuta query y guarda resultado)
DECLARE export_cursor CURSOR FOR
SELECT * FROM ventas WHERE fecha >= '2024-01-01';
-- status | cursor_name | total_rows
-- ----------------+---------------+------------
-- DECLARE CURSOR | export_cursor | 624460
-- 2. Fetch en lotes (sin saturar memoria)
FETCH 1000 FROM export_cursor; -- Primeras 1000 filas
FETCH 1000 FROM export_cursor; -- Siguientes 1000 filas
FETCH ALL FROM export_cursor; -- Resto de filas
-- 3. Cerrar cursor cuando termines
CLOSE export_cursor;Exportar a CSV con psql
# Exportar directamente a CSV (streaming, sin límite de memoria)
psql -h server -p 5433 -U oxide -d oxidedb \
-c "\copy (SELECT * FROM ventas WHERE fecha >= '2024-01-01' LIMIT ALL) TO '/tmp/export.csv' CSV HEADER"
# O usando cursores para control fino
psql -h server -p 5433 -U oxide -d oxidedb << 'EOF'
DECLARE c CURSOR FOR SELECT * FROM ventas;
\copy (FETCH 100000 FROM c) TO 'batch1.csv' CSV HEADER
\copy (FETCH 100000 FROM c) TO 'batch2.csv' CSV HEADER
CLOSE c;
EOFConfiguración DataGrip/DBeaver
Para evitar OOM en clientes GUI, configura fetch size:
DataGrip
Data Source → Advanced → defaultRowFetchSize = 200
DBeaver
Connection → Edit → Driver properties → fetchSize = 200
🔧 Configuración del Servidor
Opciones de oxidedb-server
oxidedb-server [OPTIONS]
Opciones:
-p, --port <PORT> Puerto TCP [default: 5432]
-H, --host <HOST> Dirección bind [default: 0.0.0.0]
-d, --data-dir <DIR> Directorio de datos [default: /var/lib/oxidedb]
-w, --workers <NUM> Threads de trabajo [default: CPUs detectadas]
-v, --verbose Logging detallado
--max-memory <MB> Memoria máxima [default: 4096]
--batch-size <SIZE> Tamaño batch SIMD [default: 4096]
--simd-level <LEVEL> Nivel SIMD: avx2, avx512 [default: auto]Archivo de configuración
Ubicación: /etc/oxidedb/oxidedb.conf
[server]
port = 5432
host = "0.0.0.0"
data_dir = "/var/lib/oxidedb"
max_connections = 100
[execution]
max_worker_threads = 8
max_memory_mb = 4096
simd_batch_size = 4096
enable_parallel_execution = true
[storage]
parquet_compression = "snappy"
column_chunk_size = 1048576
enable_mmap = true
[logging]
level = "info"
file = "/var/log/oxidedb/server.log"⚡ Performance - 5x Más Rápido que DuckDB
Benchmarks Reales - Dataset S3 1.9M filas
COUNT(*) Full Scan
GROUP BY + ORDER BY
Optimizaciones Aplicadas
LTO Fat
Link-Time Optimization para inlining cross-crate
AVX2 + SIMD
SSE4.2, BMI1, BMI2, FMA activados
DataFusion 50.3
Batch size 16384, predicate pushdown
Configuración de Servidor
# Iniciar con configuración optimizada
oxidedb-server --port 5433 \
--data-dir /var/lib/oxidedb \
--memory-limit 8589934592 \ # 8GB RAM
--batch-size 16384 \ # Batch grande para SIMD
--enable-s3 # Habilitar S3
# Variables de entorno para S3
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-2🚀 Deployment y Producción
Docker
# Dockerfile incluido
FROM ubuntu:22.04
COPY oxidedb-server /usr/local/bin/
COPY oxidedb-cli /usr/local/bin/
EXPOSE 5432
CMD ["oxidedb-server", "--port", "5432"]
# Ejecutar container
docker run -d \
--name oxidedb \
-p 5432:5432 \
-v /data:/var/lib/oxidedb \
oxidedb/server:1.6.0Kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
name: oxidedb
spec:
replicas: 3
selector:
matchLabels:
app: oxidedb
template:
metadata:
labels:
app: oxidedb
spec:
containers:
- name: oxidedb
image: oxidedb/server:0.1.0
ports:
- containerPort: 5432
env:
- name: OXIDEDB_MAX_MEMORY
value: "8192"