docs(storage): dedicated DB integration-guide chapters

Split the database backends into their own practical integration-guide
chapters, grounded in the implemented config/schema/features:

- observability/storage/sqlite.md
- observability/storage/postgres.md
- observability/storage/timescaledb.md
- observability/storage/mongodb.md

Each covers: build feature, running the DB (docker), the exact [storage.*]
config block and all fields, the auto-created schema/document model,
verification (incl. the gated REFLOW_TEST_* integration tests), operations
(retention/compression/sharding/backups), and troubleshooting with the real
error messages.

Nest them under Storage Backends in SUMMARY.md and add an "Integration guides"
index to storage-backends.md (now the conceptual overview; the chapters are the
walkthroughs).

Author: darmie

docs/SUMMARY.md

@@ -56,6 +56,10 @@
 - [Data Flow Tracing](observability/data-flow-tracing.md)
 - [Configuration](observability/configuration.md)
 - [Storage Backends](observability/storage-backends.md)
+  - [SQLite](observability/storage/sqlite.md)
+  - [PostgreSQL](observability/storage/postgres.md)
+  - [TimescaleDB](observability/storage/timescaledb.md)
+  - [MongoDB](observability/storage/mongodb.md)
 - [OTLP Export (Monoscope)](observability/otlp-export.md)
 - [Production Deployment](observability/deployment.md)
 

docs/observability/storage-backends.md

@@ -32,6 +32,19 @@ row/document keyed by `trace_id`, with denormalized `flow_id`/`execution_id`/
 - **MongoDB Storage** _(available, `--features mongodb`)_: Document store; the JSON-shaped trace maps naturally to a document
 - **Custom Storage**: Implement the `TraceStorage` trait yourself
 
+### Integration guides
+
+Step-by-step setup for each database — build feature, run the DB, the exact
+config block, the auto-created schema, verification, and operations:
+
+- **[SQLite](storage/sqlite.md)** — embedded, default, zero-ops
+- **[PostgreSQL](storage/postgres.md)** — production, multi-instance, high-concurrency
+- **[TimescaleDB](storage/timescaledb.md)** — Postgres + time-series hypertable (retention/compression)
+- **[MongoDB](storage/mongodb.md)** — document store
+
+This page below is the conceptual overview (model, comparison, selection); the
+guides above are the practical walkthroughs.
+
 ## Memory Storage
 
 ### When to Use

docs/observability/storage/mongodb.md

@@ -0,0 +1,91 @@
+# MongoDB Integration Guide
+
+MongoDB is a **document-store** backend — the JSON-shaped `FlowTrace` maps
+naturally onto a BSON document. A good fit if you already operate MongoDB, want
+schema-less retention of the evolving trace shape, or scale horizontally via
+sharding.
+
+## Build
+
+Behind a cargo feature (adds the `mongodb` + `bson` drivers):
+
+```bash
+cargo build -p reflow_tracing --features mongodb
+# or every durable backend at once:
+cargo build -p reflow_tracing --features all-backends
+```
+
+## Run a database
+
+```bash
+docker run -d --name reflow-mongo -p 27017:27017 mongo:7
+```
+
+## Configure
+
+Set `storage.backend` to `mongodb` (or `mongo`) and a `[storage.mongodb]` block.
+All fields:
+
+```toml
+[storage]
+backend = "mongodb"
+
+[storage.mongodb]
+connection_url  = "mongodb://localhost:27017"
+database_name   = "reflow_tracing"
+collection_name = "traces"
+```
+
+## Document model
+
+Each `FlowTrace` is one document keyed by its `trace_id` (`_id`), with
+denormalized top-level fields for querying and the full trace nested under
+`trace`:
+
+```json
+{
+  "_id": "<trace_id>",
+  "flow_id": "...", "execution_id": "...", "status": "...",
+  "start_time": 1718000000, "end_time": 1718000005, "event_count": 12,
+  "trace": { /* the full FlowTrace */ }
+}
+```
+
+Stores use an upsert (`replace_one … upsert`), and the server creates indexes on
+`flow_id`, `execution_id`, `status`, and `start_time` on startup.
+
+## Verify
+
+```bash
+reflow_tracing            # logs: "Initialized storage backend: mongodb"
+
+mongosh "mongodb://localhost:27017/reflow_tracing" \
+  --eval 'db.traces.countDocuments()'
+mongosh "mongodb://localhost:27017/reflow_tracing" \
+  --eval 'db.traces.findOne({}, {flow_id:1, status:1, event_count:1})'
+```
+
+Live integration test:
+
+```bash
+REFLOW_TEST_MONGODB_URL="mongodb://localhost:27017" \
+  cargo test -p reflow_tracing --features mongodb --test storage_backends \
+  mongodb_store_query_delete_roundtrip
+```
+
+## Operations
+
+- **Retention (TTL)**: a TTL index expires old traces automatically — e.g. add a
+  BSON `Date` field and
+  `db.traces.createIndex({ expires_at: 1 }, { expireAfterSeconds: 0 })`, or run a
+  periodic `deleteMany({ start_time: { $lt: cutoff } })`.
+- **Sharding**: shard on `_id` (trace_id) or `flow_id` for horizontal scale.
+- **Backups**: `mongodump` / replica sets.
+
+## Troubleshooting
+
+- **`MongoDB backend not compiled in`** — rebuild with `--features mongodb`.
+- **`MongoDB storage config missing`** — `backend = "mongodb"` but no
+  `[storage.mongodb]` block.
+- **Connection errors** — check `connection_url`, that the server is up, and auth
+  (`mongodb://user:pass@host:27017`).

docs/observability/storage/postgres.md

@@ -0,0 +1,94 @@
+# PostgreSQL Integration Guide
+
+PostgreSQL is the recommended backend for **production, multi-instance, and
+high-concurrency** deployments — a real server with connection pooling and strong
+durability. For time-series-heavy workloads, see the
+[TimescaleDB guide](timescaledb.md), which reuses this same config.
+
+## Build
+
+PostgreSQL is behind a cargo feature (adds the sqlx Postgres driver):
+
+```bash
+cargo build -p reflow_tracing --features postgres
+# or every durable backend at once:
+cargo build -p reflow_tracing --features all-backends
+```
+
+## Run a database
+
+```bash
+docker run -d --name reflow-pg \
+  -e POSTGRES_DB=traces -e POSTGRES_USER=reflow -e POSTGRES_PASSWORD=secret \
+  -p 5432:5432 postgres:16
+```
+
+## Configure
+
+Set `storage.backend` to `postgres` (or `postgresql`) and a `[storage.postgres]`
+block. All fields:
+
+```toml
+[storage]
+backend = "postgres"
+
+[storage.postgres]
+connection_url       = "postgresql://reflow:secret@localhost:5432/traces"
+max_connections      = 20
+min_connections      = 5
+acquire_timeout_secs = 5
+```
+
+## Schema
+
+Created automatically on startup (the `traces` table + indexes) — no manual DDL.
+Each `FlowTrace` is one row: the full trace as a (zstd-compressed when large)
+JSON `BYTEA` blob, plus denormalized columns:
+
+| column | type | purpose |
+|---|---|---|
+| `trace_id` (PK) | `TEXT` | identity |
+| `flow_id`, `execution_id`, `status` | `TEXT` | query filters |
+| `start_time`, `end_time` | `BIGINT` | time-range queries |
+| `event_count` | `BIGINT` | stats without loading the blob |
+| `data`, `compressed`, `size_bytes` | `BYTEA`/`BOOL`/`BIGINT` | payload |
+
+Stores are **synchronous** with an `INSERT … ON CONFLICT (trace_id) DO UPDATE`
+upsert (idempotent re-finalize), and indexes cover `flow_id`, `execution_id`,
+`status`, `start_time`.
+
+## Verify
+
+```bash
+reflow_tracing            # logs: "Initialized storage backend: postgres"
+
+psql "$CONN" -c '\dt'                          # traces
+psql "$CONN" -c 'SELECT count(*) FROM traces;'
+```
+
+Run the bundled integration test against a live instance:
+
+```bash
+REFLOW_TEST_POSTGRES_URL="postgresql://reflow:secret@localhost:5432/traces" \
+  cargo test -p reflow_tracing --features postgres --test storage_backends \
+  postgres_store_query_delete_roundtrip
+```
+
+## Operations
+
+- **Pooling**: size `max_connections` to your collector concurrency; `sqlx`
+  manages the pool with `acquire_timeout_secs`.
+- **Retention**: schedule
+  `DELETE FROM traces WHERE start_time < EXTRACT(EPOCH FROM now() - INTERVAL '30 days')`,
+  or use [TimescaleDB](timescaledb.md) for native retention.
+- **Backups**: standard `pg_dump` / streaming replication / PITR.
+- **Scale**: read replicas, partitioning. If your queries are dominated by
+  time ranges, TimescaleDB's hypertable is a better fit.
+
+## Troubleshooting
+
+- **`PostgreSQL backend not compiled in`** — rebuild with `--features postgres`.
+- **`PostgreSQL storage config missing`** — `backend = "postgres"` but no
+  `[storage.postgres]` block.
+- **Connection refused / auth failed** — check `connection_url`, that the server
+  is reachable, and credentials.

docs/observability/storage/sqlite.md

@@ -0,0 +1,83 @@
+# SQLite Integration Guide
+
+SQLite is the **default durable backend** — a single embedded file, no server to
+run. Ideal for development, single-node deployments, and anywhere you want
+persistence without operating a database.
+
+## Build
+
+SQLite ships in the default build (the `storage` feature is on by default):
+
+```bash
+cargo build -p reflow_tracing            # SQLite included
+```
+
+## Configure
+
+Set `storage.backend = "sqlite"` and a `[storage.sqlite]` block. All fields:
+
+```toml
+[storage]
+backend = "sqlite"
+
+[storage.sqlite]
+database_path = "traces.db"   # file path, or ":memory:" for an ephemeral DB
+wal_mode      = true          # Write-Ahead Logging (recommended)
+journal_mode  = "WAL"
+synchronous   = "NORMAL"      # NORMAL is a good durability/speed balance
+cache_size    = -2000         # KB when negative (here ~2 MB), pages when positive
+```
+
+The database file is **created automatically** if it doesn't exist (the server
+opens it with `mode=rwc`); the parent directory must already exist.
+
+## Schema
+
+Created on startup — you never run DDL by hand. Each `FlowTrace` is stored as one
+row in `traces`: the full trace is a (zstd-compressed when large) JSON blob in
+`data`, alongside denormalized columns for querying:
+
+| column | purpose |
+|---|---|
+| `trace_id` (PK) | trace identity |
+| `flow_id`, `execution_id`, `status` | query filters |
+| `start_time`, `end_time` | time-range queries |
+| `data` (BLOB), `compressed`, `size_bytes` | the trace payload |
+
+Indexes cover `flow_id`, `execution_id`, `status`, `start_time`. Writes are
+**synchronous (write-through)**, so a trace is queryable the instant it's stored.
+
+## Verify
+
+```bash
+# point the server at a sqlite config and start it
+reflow_tracing            # logs: "Initialized storage backend: sqlite"
+
+# after some traces have flowed, inspect the file directly
+sqlite3 traces.db '.tables'                       # traces, trace_events
+sqlite3 traces.db 'SELECT count(*) FROM traces;'
+```
+
+Or query through the protocol (`get_trace` / `query_traces`) from any SDK / the
+monitoring client.
+
+## Operations
+
+- **Backups**: it's a single file — copy it (use the SQLite backup API or copy
+  while WAL-checkpointed). The WAL (`traces.db-wal`) must travel with the file.
+- **Concurrency**: SQLite is single-writer. Fine for one collector; for high
+  concurrent write volume move to [PostgreSQL](postgres.md) /
+  [TimescaleDB](timescaledb.md).
+- **Retention**: SQLite has no automatic TTL. Prune with
+  `DELETE FROM traces WHERE start_time < strftime('%s','now','-30 days')` on a
+  schedule, or use the in-process delete API.
+- **Cache**: bump `cache_size` (negative = KB) for read-heavy workloads.
+
+## Troubleshooting
+
+- **`unable to open database file`** — the parent directory doesn't exist, or the
+  process can't write there. Create the directory / fix permissions.
+- **No traces appear** — confirm `backend = "sqlite"` (not `memory`) and that the
+  network's `TracingConfig.enabled = true` points at this server.
+- **`Storage feature is not enabled`** — you built with `--no-default-features`;
+  re-enable the `storage` feature.