Volver

OxideDB Docs

Documentación Completa

📚 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

bash
# 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 --version

Conectar con psql (PostgreSQL)

bash
# 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

bash
# 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:

sql
-- 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 S3

Delta Lake con Time Travel

sql
-- 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

bash
# 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:

sql
-- 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

sql
-- 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:

sql
-- 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:

sql
-- 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:

sql
-- 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

bash
# 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;
EOF

Configuració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

bash
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

ini
[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

OxideDB (Server GCP)0.75s
DuckDB (Local)3.43s
4.6x más rápido

GROUP BY + ORDER BY

OxideDB (Server GCP)1.17s
DuckDB (Local)5.86s
5.0x más rápido

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

bash
# 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
# 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.0

Kubernetes

yaml
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"