Driver Support

ROSQL compiles to SQL and executes against your telemetry data. Each backend is enabled via a Cargo feature flag.

Supported backends

Backend	Feature flag	CLI flag	Status
Parquet files (local / S3) powered by DuckDB	duckdb	--backend parquet	✅ v0.4.5
PostgreSQL / TimescaleDB	postgres	--backend postgres	✅ v0.1
MySQL / MariaDB	mysql	--backend mysql	✅ v0.1
AWS Athena	athena	—	📋 Planned
Google BigQuery	bigquery	—	📋 Planned

Feature flags

Feature	What it enables	Runtime deps
(default)	Parser, AST, unit system, SQL compiler, proto types	logos, serde, prost
duckdb	Parquet file backend (local + S3) powered by DuckDB — use with --backend parquet	duckdb (bundled), tokio
postgres	PostgreSQL / TimescaleDB driver	sqlx, tokio
mysql	MySQL / MariaDB driver	sqlx, tokio
server	rosql CLI binary + gRPC server	tonic, tokio, clap
wasm	WASM exports for browser editors	wasm-bindgen

Installing

One-liner (Linux x86_64 / arm64 · macOS Apple Silicon)

curl -fsSL https://rosql.org/install.sh | sh

Pre-built binaries include the Parquet backend (--backend parquet) out of the box.

Build from source

# Parquet backend + CLI (recommended — no external database required)
cargo install rosql --features server,duckdb

# PostgreSQL driver + CLI
cargo install rosql --features server,postgres

# MySQL driver + CLI
cargo install rosql --features server,mysql

# Multiple backends
cargo install rosql --features server,duckdb,postgres,mysql

# Library only (no CLI, no runtime)
cargo add rosql

Windows / Intel Mac

Pre-built binaries are not available for Windows or Intel Macs. Use cargo install above.

---

Parquet backend

DuckDB runs embedded and reads Parquet files directly from a local directory or S3 — no external server required. Use this backend with telemetry files produced by the Robot Ops demo-agent or any compatible OTel exporter.

# Local directory
rosql query "FROM traces WHERE status = 'ERROR' SINCE 1 hour ago" \
  --backend parquet \
  --url ./telemetry/robotops_demo_agent/20260403-141530/

# S3
rosql query "FROM traces WHERE status = 'ERROR' SINCE 1 hour ago" \
  --backend parquet \
  --url s3://my-bucket/robot-01/robotops_demo_agent/20260403-141530/

Expected directory layout

The --url argument must point to a directory with this structure:

<url>/
  traces/          *.parquet  →  otel_traces view
  logs/            *.parquet  →  otel_logs view
  metrics/         *.parquet  →  otel_metrics view
  topic_messages/  *.parquet  →  topic_messages view
  mcap_metadata/   *.parquet  →  mcap_metadata view

Files are discovered recursively using **/*.parquet globs. Each subdirectory can contain multiple Parquet files (e.g., one per hour or per recording session). Missing subdirectories are silently skipped — queries against absent tables return a clear DataSourceUnavailable error.

S3 credentials

When --url s3://... is used, ROSQL automatically loads the DuckDB httpfs extension. Set credentials via standard AWS environment variables:

Variable	Description
AWS_ACCESS_KEY_ID	Static access key
AWS_SECRET_ACCESS_KEY	Static secret key
AWS_REGION / AWS_DEFAULT_REGION	AWS region (e.g. us-east-1)
AWS_PROFILE	Named credentials profile
AWS_ENDPOINT_URL	Override endpoint for S3-compatible storage (MinIO, Cloudflare R2 etc.)

Use cases

• Local telemetry replay — query Parquet exports from the demo-agent without standing up a database
• S3 telemetry archives — query recordings stored on S3 directly
• CI/testing — no Docker or external service required
• Offline environments — works without network access to a database server

---

PostgreSQL / TimescaleDB

rosql query "FROM traces WHERE status = 'ERROR'" \
  --backend postgres \
  --url postgresql://user:pass@localhost:5432/telemetry

Connection string format: postgresql://[user[:password]@][host][:port]/database

TimescaleDB is fully supported — ROSQL uses standard PostgreSQL queries that work transparently with hypertables.

---

MySQL / MariaDB

rosql query "FROM traces WHERE status = 'ERROR'" \
  --backend mysql \
  --url mysql://user:pass@localhost:3306/telemetry

Connection string format: mysql://[user[:password]@][host][:port]/database

---

Schema profiles

Different OTel Collector exporters use different column naming conventions. Select the profile matching your exporter:

Profile	Column convention	Example	Default for
otel-postgres	lowercase	trace_id, status_code	All backends (default)
otel-clickhouse	PascalCase	TraceId, StatusCode	ClickHouse

rosql compile "FROM traces WHERE status = 'ERROR'" \
  --backend parquet \
  --schema otel-postgres

If your column names don't match either profile, custom schema profiles are tracked in #22.

---

Schema requirements

Your Parquet files or database must have the OTel tables ROSQL expects. See the Schema Reference → for complete DDL.

Required tables for basic functionality:

• otel_traces
• otel_logs
• otel_metrics

Optional tables for advanced features:

• topic_messages — enables FROM topics, topic aliases (FROM odom, etc.), PATH DEVIATION, JOINT DEVIATION
• mcap_metadata — enables FROM recordings