---
title: Driver Support
description: Supported database backends for ROSQL — Parquet (local/S3), PostgreSQL, MySQL, and more
sidebar_position: 2
keywords: [rosql, postgresql, mysql, duckdb, parquet, s3, database, driver, backend]
---

# 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](https://github.com/RobotOpsInc/rosql/issues/9) |
| Google BigQuery | `bigquery` | — | 📋 [Planned](https://github.com/RobotOpsInc/rosql/issues/10) |

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

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

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

### Build from source

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

:::note 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](https://github.com/RobotOpsInc/rmw_robotops/tree/development/demo-agent) or any compatible OTel exporter.

```bash
# 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, Ceph, 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

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

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

```bash
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](https://github.com/RobotOpsInc/rosql/issues/22).

---

## Schema requirements

Your Parquet files or database must have the OTel tables ROSQL expects. See the [Schema Reference →](./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`
