feat: read metrics from a SQL query via from_sql (DuckDB) (#52)

[msto]

Summary

Fixes #52

MetricReader was text-IO-only: reading metrics that already live in Parquet, Arrow, or a database meant routing through a TSV intermediary. This adds MetricReader.from_sql(metric_class, query, *, connection=None) (and an eager Metric.from_sql(query) mirroring Metric.read), which validates the rows of a SQL query as metrics. The query names its own source, so any backend DuckDB can read works — Parquet/Arrow/JSON/CSV/SQLite/Postgres/S3 — and fgmetric reimplements no parsing.

DuckDB is an optional dependency (fgmetric[duckdb]) and an implementation detail: it's imported lazily inside the single helper that touches it (_duckdb.query_rows), so importing fgmetric and the text path never require it. A missing duckdb raises a friendly ImportError. Without a connection, a transient in-memory connection is opened and closed internally; a supplied connection is borrowed and never closed (for Postgres/secrets/ATTACH).

The existing text path is unchanged. from_sql is an additive sibling constructor — open/read/__init__ keep their behavior; both paths funnel into the same model_validate core via a shared _from_records. Unlike open, from_sql is not a context manager (it owns no file handle).

Test plan

• New tests/test_from_sql.py covers native typing, NULL→None, AS column→field renaming, field-alias resolution, missing-column ValidationError, empty result, transient vs. borrowed-connection lifecycle (borrowed never closed), a Parquet round-trip, both reader- and Metric-level entry points, and the friendly ImportError when duckdb is absent.
• poe check-all green: ruff format + lint, mypy strict, 195 tests at 98% coverage; confirmed import fgmetric does not load duckdb.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b63497f0-43a0-4b0c-bb59-999375b9ffd4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}