duckbill 0.1.0__tar.gz

duckbill-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+examples/questions/
+.vendor/
+# standalone bundles are regenerable build artifacts (duckbill bundle -> a single
+# uv-run .py); they embed the warehouse data and are too large to track.
+/dashboard.py
+/slowq.py

duckbill-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: duckbill
+Version: 0.1.0
+Summary: Live, query-backed dashboards over a local DuckDB, declared as Python data.
+Requires-Python: >=3.9
+Requires-Dist: duckdb>=0.10
+Requires-Dist: pytz
+Requires-Dist: sqlglot>=20
+Provides-Extra: all
+Requires-Dist: psycopg[binary]>=3; extra == 'all'
+Requires-Dist: pymysql; extra == 'all'
+Requires-Dist: snowflake-connector-python; extra == 'all'
+Provides-Extra: mysql
+Requires-Dist: pymysql; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3; extra == 'postgres'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python; extra == 'snowflake'

duckbill-0.1.0/README.md

@@ -0,0 +1,316 @@
+# duckbill
+
+Live, query-backed dashboards declared as Python data. A dashboard is a Python
+file that defines charts as dicts; the server runs each chart's SQL on every
+request, so the page is live -- it re-queries on interaction and reflects the
+current warehouse. No build step, two dependencies (`duckdb` + `sqlglot`); network
+backends are opt-in extras. Single process.
+
+> Part of **duckpond**, a two-part local-DuckDB toolkit. **duckbill** (this) serves
+> and shares a warehouse as a live dashboard; its sibling **ducktail** pulls
+> scattered sources into one. duckbill works against any DuckDB/SQLite store --
+> ducktail-built or not.
+
+```
+pip install -e .
+duckbill serve examples/rds_slowq.py --db /path/to/warehouse.duckdb
+```
+
+## Backends
+
+The `--db` flag accepts a DSN or a bare file path:
+
+| DSN form | backend |
+|---|---|
+| `/path/to/file.duckdb` or `duckdb:///path/to/file.duckdb` | DuckDB (local file) |
+| `sqlite:///path/to/file.db` | SQLite (local file) |
+| `postgresql://user:pass@host/db` | Postgres |
+| `mysql://user:pass@host/db` | MySQL |
+| `snowflake://user@account/db/schema?warehouse=W&role=R` | Snowflake |
+
+Secret values (passwords, tokens) should not be written into command lines or
+dashboard files. Use `${VAR}` in the DSN; duckbill expands it from the
+environment before connecting:
+
+```
+duckbill serve dash.py --db "postgresql://ro_user:${DB_PASS}@db-host:5432/warehouse"
+```
+
+Network backends (Postgres, MySQL, Snowflake) are opt-in extras; the base
+install only pulls in `duckdb` and `sqlglot`:
+
+```
+pip install duckbill[postgres]    # psycopg
+pip install duckbill[mysql]       # pymysql
+pip install duckbill[snowflake]   # snowflake-connector-python
+pip install duckbill[all]         # all three
+```
+
+All connections are read-only. For DuckDB and SQLite that is enforced at the
+driver level. For network backends, use a read-only role or user -- Snowflake
+has no session-level read-only toggle, so this is especially important there.
+
+`--pool` sets the connection pool size for network backends (default 4); it has
+no effect on DuckDB or SQLite.
+
+`$name` parameter binding is uniform across all backends -- the server translates
+the dashboard's `$name` placeholders to the native paramstyle before executing.
+SQL dialect (functions, casts, date arithmetic) is the author's responsibility:
+write SQL that matches the backend you deploy against.
+
+Bundles (`duckbill bundle`) are DuckDB/SQLite-only. A bundle embeds the warehouse
+tables as Parquet in a self-contained `uv run` server script; network backends are
+serve-only (they can't export to Parquet). A bundle never contains credentials --
+the DSN is used at build time to export data and is not written into the output.
+
+## Declaring a dashboard
+
+A dashboard module defines `charts`, and optionally `params`, `title`, and a
+`readme` (see [Documentation](#documentation)):
+
+```python
+title = "my warehouse"
+
+params = [
+    {"name": "window", "control": "timespan", "default": "31d",
+     "presets": ["6h", "24h", "7d", "31d"]},          # binds $start and $end
+    {"name": "kind", "control": "select", "default": "all",
+     "choices_sql": "SELECT DISTINCT kind FROM warehouse.t ORDER BY 1"},
+    {"name": "id", "default": "", "control": "none"},  # set by a drill click
+]
+
+charts = [
+    {"id": "volume", "section": "Overview", "title": "Volume", "type": "line",
+     "brush": "timespan",                              # drag the x-axis to zoom
+     "sql": """SELECT to_timestamp(ts) AS t, n FROM warehouse.t
+               WHERE to_timestamp(ts) >= $start::TIMESTAMPTZ
+                 AND to_timestamp(ts) <  $end::TIMESTAMPTZ
+                 AND ($kind = 'all' OR kind = $kind) ORDER BY t""",
+     "encoding": {"x": {"field": "t", "type": "temporal"},
+                  "y": {"field": "n", "type": "quantitative"}}},
+]
+```
+
+### Charts
+
+| key        | meaning |
+|------------|---------|
+| `id`       | unique identifier (required) |
+| `title`    | card heading (required) |
+| `type`     | `line` / `bar` / `stacked-bar` / `area` / `point` / `table` / `metric` / `leaderboard` / `spec` (required) |
+| (table col) | a `table` query column named `_*` is data-only: kept for drill values, not displayed |
+| `sql`      | the query; may reference `$param` (required) |
+| `section`  | groups cards under a heading (default `Overview`) |
+| `encoding` | Vega-Lite encoding for the built-in types |
+| `spec`     | raw Vega-Lite spec -- the escape hatch, used when `type` is `spec` |
+| `drill`    | bars: `{"param": p, "field": col}` -- click a mark to open param `p`'s detail page. tables: `{column: param}` or `{column: {param, value}}` -- click a cell to drill (a `value` column, or one named `_*`, supplies the param value when it differs from the displayed text) |
+| `brush`    | `"timespan"`: drag the x-axis to set the window |
+| `markers`  | `true` (all marker sets) or `["id", ...]`: overlay marker rules on this chart |
+| `span`     | `"full"` -- the card spans the whole row; an integer `N` -- it spans `N` columns (clamped to the columns that fit, so it degrades to full width on a narrow window) |
+
+`sql` is bound, not interpolated -- the server passes `$param` values to DuckDB as
+parameters, so control and drill input is safe. The dashboard module is your own
+trusted code; its SQL runs as written.
+
+### Metric cards
+
+A `metric` chart is a strip of hero figures rather than a plot. Its SQL returns
+**one row**; each column becomes a figure -- the value shown large and compacted
+(`30.2k`, `1.2M`), the column name as the label. Use a quoted alias to control
+the label, and pair it with `"span": "full"` for a hero row across the top:
+
+```python
+{"id": "summary", "section": "Overview", "title": "Slow-log summary", "type": "metric", "span": "full",
+ "sql": f"""SELECT count(*) AS "slow entries", round(sum(query_time_s)) AS "total query time (s)",
+                   count(DISTINCT fingerprint_hash) AS "fingerprints"
+            FROM warehouse.entries WHERE {{window}}"""}
+```
+
+When the query references the timespan (`$start`/`$end`), each numeric figure
+also shows its change versus the previous equal-length window, as a signed
+percent colored by whether the move is good or bad. `good` declares the good
+direction -- `"up"` (higher is better), `"down"` (lower is better), or
+`"neutral"` (no judgment, gray) -- either for all figures or per figure:
+
+```python
+"good": {"slow entries": "down", "total query time (s)": "down", "fingerprints": "neutral"}
+```
+
+Figures not listed default to `"up"`. The delta is omitted when there's no prior
+window or the previous value is zero/absent.
+
+A metric may also carry a `spark` query -- SQL returning a temporal column plus
+one column per figure (aliases matched by name) -- and each figure gets an inline
+sparkline of that trend:
+
+```python
+"spark": f"""SELECT date_trunc('hour', t) AS hour, count(*) AS "slow entries", ...
+             FROM warehouse.entries WHERE {{window}} GROUP BY 1 ORDER BY 1"""
+```
+
+### Leaderboards
+
+A `leaderboard` is a ranked list for top-N-by-dimension: SQL returns rows whose
+first text column is the label and first numeric column the value, drawn with an
+inline magnitude bar behind each value. It drills like a bar (`{"param", "field"}`,
+clicking a row navigates to that param's detail page; a `_`-prefixed column can
+carry a hidden drill value, e.g. show readable text but drill on a hash). Denser
+and more scannable than a bar chart for a long ranking.
+
+### Compare
+
+The **Compare** toggle (in the timespan control) overlays the previous
+equal-length window: a faded previous-period series on single-series time charts,
+and a `Δ%` per row on windowed leaderboards. The prev/next arrows step the window
+back/forward by its own length.
+
+### Enlarge and explore
+
+Every card has an expand icon (top-right, on hover). Clicking it opens the chart
+in a large modal where you can flip between the **Chart** and the raw **Data**
+table, and **Open in Ask** to drop the chart's query (with the current params
+substituted) into the Ask workbench for ad-hoc exploration.
+
+### Params
+
+A param drives a control and binds into SQL by its `name`. Controls:
+
+- `select` -- a dropdown; options come from `choices` (a list) or `choices_sql`.
+- `timespan` -- a time-range picker (presets + custom from/to + brush-to-zoom).
+  It binds `$start` and `$end` (ISO timestamps), not a param of its own name.
+- `none` -- no control; the param is set only by a drill click.
+
+`type` is `str` (default), `int`, or `float`.
+
+### Markers
+
+A `markers` list declares overlay queries -- the canonical case is deploy
+markers, a recurring motif. Each marker is `{"id", "sql", "field"}` plus optional
+`label` and `color`; the `sql` returns timestamps (referencing `$param` like any
+query), and any chart with `markers: true` gets those timestamps drawn as rules.
+
+```python
+markers = [
+    {"id": "deploys", "field": "t", "label": "label", "color": "#b9c2cc",
+     "sql": "SELECT to_timestamp(build_time) AS t, version AS label FROM warehouse.deploys "
+            "WHERE to_timestamp(build_time) >= $start::TIMESTAMPTZ "
+            "  AND to_timestamp(build_time) <  $end::TIMESTAMPTZ"},
+]
+```
+
+Window the marker query on `$start`/`$end` so rules stay inside the chart's time
+axis. Markers re-run when the window changes.
+
+## Documentation
+
+A warehouse documents itself from two sources, both surfaced in the header's
+**About** tab and by `duckbill docs`:
+
+- the dashboard's `readme` -- a Markdown string for the narrative: what the
+  warehouse is, how the pieces fit, how to read the dashboard.
+- DuckDB `COMMENT`s -- per-table and per-column descriptions that live in the
+  warehouse catalog, so the schema reference is generated, not hand-maintained.
+
+```python
+readme = """\
+This warehouse stitches together the slow log, Performance Insights, and ALB
+access logs so a slow query can be traced out to the request that issued it.
+
+Times are stored as epoch seconds (`logged_at`); the charts convert with
+`to_timestamp`.
+"""
+```
+
+Set the `COMMENT`s where the warehouse is built, so they survive a rebuild:
+
+```sql
+COMMENT ON TABLE warehouse.entries IS 'One row per slow-query log entry, fingerprinted.';
+COMMENT ON COLUMN warehouse.entries.logged_at IS 'When the statement was logged, epoch seconds (UTC).';
+```
+
+The About view renders the `readme` and a schema reference (each table's comment
+and its columns with types and comments); the Ask sidebar hangs the same comments
+off tables and columns as tooltips. To emit a `WAREHOUSE.md` for the repo:
+
+```
+duckbill docs examples/rds_slowq.py --db warehouse.duckdb -o WAREHOUSE.md
+```
+
+## Ask (ad-hoc queries)
+
+The header's **Ask** tab is a query workbench, like Metabase's native query: a
+schema sidebar (click to insert), a CodeMirror SQL editor with schema-aware
+autocomplete, and a Run button (⌘/Ctrl+Enter). Results show as a table, or pick a
+chart type + x/y/color to visualize through the same chart engine (tooltips,
+hover crosshair, interactive legend included). The query is read-only -- the
+connection is `read_only`, so it's SELECT-only -- and results are row-capped.
+
+**Save** names a question and writes it to a file -- one JSON per question under
+`questions/` next to the dashboard (override with `--questions <dir>`), so they're
+git-friendly and hand-editable. The **Saved** dropdown reopens or deletes them,
+and each has a stable link (`#q=<slug>`). **Copy link** is the no-save path: it
+encodes the SQL and chart choice into the URL (`#ask=…`).
+
+## Standalone bundle
+
+Wrap a dashboard and its data into one self-contained file for sharing or
+archiving:
+
+```
+duckbill bundle examples/rds_slowq.py --db warehouse.duckdb -o dashboard.py
+# -> dashboard.py   (run it with: uv run dashboard.py)
+```
+
+`bundle` prunes the warehouse first -- only the tables and columns the charts
+actually reference are included -- exports them to zstd Parquet, and embeds that
+(b85) in a single `uv run`-able Python script. The recipient runs `uv run
+dashboard.py`; uv resolves the deps from the PEP 723 header, the script extracts
+its embedded Parquet to a content-keyed temp dir on first run (later runs reuse
+it), an in-memory DuckDB exposes each table as a view `warehouse.<table>`, and a
+browser renders the dashboard. No duckbill install, no static host, no sibling
+files -- just one script and uv.
+
+Queries run server-side (it's a tiny localhost http server), so it works in every
+browser and the whole dashboard stays live: drill-down, the timespan brush, legend
+filters, and the Ask view all work. The only degradation is that saved questions
+are read-only -- the ones embedded at build time are loadable, but new ones can't
+be persisted into the bundle.
+
+Bundles are DuckDB/SQLite-only -- a bundle embeds the data as Parquet, which a
+network backend can't export. A bundle never contains credentials; the DSN is used
+only at build time.
+
+## How it works
+
+- **The dashboard module** is pure data -- charts and params, plus whatever Python
+  you want for shared SQL fragments and computed defaults.
+- **The server** holds one read-only DuckDB connection behind a lock and serves
+  `/` (the page), `/meta` (params + chart metadata), `/q` (run one chart's SQL),
+  and `/docs` (the readme + catalog comments). It binds only the params each
+  query references.
+- **The page** builds controls from the params, draws each chart with Vega-Lite,
+  and re-queries only the charts that reference a changed param.
+
+### Pages and drill-down
+
+Every section is a page. Sections not driven by a drill are the home page; each
+drill param has its own detail page -- the section whose charts all reference it.
+Clicking a drill mark navigates to that detail page (the current page lives in
+the URL hash, so the browser back button and shareable links work); the home
+page's other charts stay put. A detail page populates from its drill value, or,
+on a direct link with no value, from a SQL default like
+`COALESCE(NULLIF($route, ''), (SELECT ... LIMIT 1))`.
+
+A control appears only when a chart on the current page references its param, so
+a home-only filter hides on a detail page that ignores it. The header is pinned.
+
+A chart with a color series gets an interactive legend: click an entry to focus
+that series (the rest dim), click again to clear, shift-click for several. This
+filters within the chart and never drills.
+
+## Not in scope
+
+Client-side crossfilter (that's [Mosaic](https://github.com/uwdata/mosaic)),
+multi-user/auth/sharing (loopback, single user), and static export (the point is
+to stay live). Charts that need a layered/transformed view use the `spec` escape
+hatch; reference overlays (deploys, incidents) use `markers`.

duckbill-0.1.0/duckbill/__init__.py

@@ -0,0 +1,15 @@
+"""duckbill -- live, query-backed dashboards over a local DuckDB.
+
+A dashboard is a plain Python module that defines `charts` (and optionally
+`params` and `title`) as data. The server runs each chart's SQL per request, so
+the page is live: it re-queries on every interaction and reflects the current
+warehouse.
+"""
+
+from .core import Dashboard, Warehouse, params_in
+from .loader import DashboardError, load_dashboard
+from .server import serve
+
+__all__ = ["Dashboard", "Warehouse", "params_in", "load_dashboard",
+           "DashboardError", "serve"]
+__version__ = "0.1.0"

duckbill-0.1.0/duckbill/backends/__init__.py

@@ -0,0 +1,48 @@
+"""open_backend: pick a Backend from a DSN, expanding ${VAR} from the environment.
+
+A bare path (no scheme) is treated as a DuckDB file (`--db /x.duckdb`).
+Network drivers are imported lazily inside their module, so a missing extra
+errors only when that backend is selected.
+"""
+
+import os
+import re
+from urllib.parse import urlparse
+
+from .base import Backend  # re-exported for callers
+
+_VAR = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def _expand(dsn):
+    return _VAR.sub(lambda m: os.environ.get(m.group(1), ""), dsn)
+
+
+def open_backend(dsn, *, read_only=True, pool=4):
+    dsn = _expand(dsn)
+    scheme = urlparse(dsn).scheme
+
+    if scheme in ("", "duckdb", "file"):
+        from .duckdb import DuckDBBackend
+        path = dsn
+        if scheme:
+            path = dsn.split("://", 1)[1]
+        return DuckDBBackend(path, read_only=read_only)
+
+    if scheme == "sqlite":
+        from .sqlite import SQLiteBackend
+        return SQLiteBackend(dsn.split("://", 1)[1], read_only=read_only)
+
+    if scheme in ("postgres", "postgresql"):
+        from .postgres import PostgresBackend
+        return PostgresBackend(dsn, read_only=read_only, pool=pool)
+
+    if scheme == "mysql":
+        from .mysql import MySQLBackend
+        return MySQLBackend(dsn, read_only=read_only, pool=pool)
+
+    if scheme == "snowflake":
+        from .snowflake import SnowflakeBackend
+        return SnowflakeBackend(dsn, read_only=read_only, pool=pool)
+
+    raise ValueError(f"unknown backend scheme {scheme!r} in {dsn!r}")

duckbill-0.1.0/duckbill/backends/base.py

@@ -0,0 +1,262 @@
+"""Backend surface plus the dialect-aware parameter scan shared by every backend.
+
+`$name` is the one author-facing bind placeholder. Discovery and translation are
+the same scan: sqlglot tokenizes the SQL for the backend's dialect so we know the
+source spans of string literals, quoted identifiers, and dollar-quoted bodies;
+comment spans we add ourselves (guarded by those string spans). A `$name` counts
+only when it falls outside every protected span. We use sqlglot to find non-code
+regions, not to interpret `$name` -- which is a duckbill convention, not native
+to each dialect.
+"""
+
+import queue
+import re
+import threading
+from contextlib import contextmanager
+from datetime import date, datetime, time
+from decimal import Decimal
+
+import sqlglot
+
+_PARAM = re.compile(r"\$([A-Za-z_][A-Za-z0-9_]*)")
+
+# sqlglot token types whose source span is non-code: string literals (incl.
+# Postgres/Snowflake dollar-quoting -> HEREDOC/RAW) and quoted identifiers.
+_PROTECTED_TOKENS = {
+    "STRING", "HEREDOC_STRING", "RAW_STRING", "NATIONAL_STRING",
+    "BYTE_STRING", "HEX_STRING", "BIT_STRING", "IDENTIFIER",
+}
+# Line-comment markers; only MySQL adds '#'. Block comments /* */ are universal.
+_LINE_COMMENTS = {"mysql": ("--", "#")}
+
+_STYLE = {
+    "duckdb": lambda n: f"${n}",      # native; passthrough
+    "sqlite": lambda n: f":{n}",      # sqlite3 named paramstyle
+    "pyformat": lambda n: f"%({n})s",  # psycopg / PyMySQL / snowflake-connector
+}
+
+
+def _in(spans, i):
+    return any(a <= i <= b for a, b in spans)
+
+
+def _comment_spans(sql, dialect, str_spans):
+    markers = _LINE_COMMENTS.get(dialect, ("--",))
+    spans, i, n = [], 0, len(sql)
+    while i < n:
+        if _in(str_spans, i):  # a marker inside a string is not a comment
+            i += 1
+            continue
+        if sql.startswith("/*", i):
+            j = sql.find("*/", i + 2)
+            j = n - 1 if j < 0 else j + 1
+            spans.append((i, j))
+            i = j + 1
+            continue
+        if any(sql.startswith(m, i) for m in markers):
+            j = sql.find("\n", i)
+            j = n - 1 if j < 0 else j - 1
+            spans.append((i, j))
+            i = j + 1
+            continue
+        i += 1
+    return spans
+
+
+def _protected(sql, dialect):
+    try:
+        toks = sqlglot.tokenize(sql, dialect=dialect)
+    except Exception:  # a tokenize failure must not blank the chart -- protect nothing
+        toks = []
+    str_spans = [(t.start, t.end) for t in toks if t.token_type.name in _PROTECTED_TOKENS]
+    return str_spans + _comment_spans(sql, dialect, str_spans)
+
+
+def referenced_params(sql, dialect="duckdb"):
+    """The set of $name placeholders a query references, ignoring those inside
+    strings, quoted identifiers, comments, or dollar-quoted bodies."""
+    spans = _protected(sql, dialect)
+    return {m.group(1) for m in _PARAM.finditer(sql) if not _in(spans, m.start())}
+
+
+def bind(sql, args, dialect, paramstyle):
+    """Translate $name to the driver's paramstyle and bind only referenced params.
+
+    Returns (translated_sql, params). For 'pyformat' backends, literal '%' in the
+    SQL is escaped to '%%' so LIKE patterns survive the driver's own substitution.
+    """
+    spans = _protected(sql, dialect)
+    fmt = _STYLE[paramstyle]
+    esc = (lambda s: s.replace("%", "%%")) if paramstyle == "pyformat" else (lambda s: s)
+    out, last, used = [], 0, set()
+    for m in _PARAM.finditer(sql):
+        if _in(spans, m.start()):
+            continue
+        name = m.group(1)
+        out.append(esc(sql[last:m.start()]))
+        out.append(fmt(name))
+        last = m.end()
+        used.add(name)
+    if not used:
+        return sql, {}          # no binds -> run() calls execute(q) with no driver
+                                # %-substitution, so the SQL must stay verbatim
+    out.append(esc(sql[last:]))
+    return "".join(out), {k: v for k, v in args.items() if k in used}
+
+
+def jsonable(v):
+    """Coerce a driver value to something the JSON encoder and Vega accept."""
+    if isinstance(v, Decimal):
+        return float(v)
+    if isinstance(v, (datetime, date, time)):
+        return v.isoformat()
+    if isinstance(v, (bytes, bytearray, memoryview)):
+        return bytes(v).hex()
+    return v
+
+
+def jsonable_row(row):
+    return [jsonable(v) for v in row]
+
+
+class Backend:
+    """The surface the server and bundler speak. Subclasses implement these.
+
+    dialect:    sqlglot dialect name for the scan
+    paramstyle: key into _STYLE for bind()
+    bundleable: can `duckbill bundle` embed this backend's data?
+    """
+
+    dialect = "duckdb"
+    paramstyle = "duckdb"
+    bundleable = False
+
+    def run(self, sql, args):
+        raise NotImplementedError
+
+    def query(self, sql, limit=2000):
+        raise NotImplementedError
+
+    def docs(self):
+        raise NotImplementedError
+
+    def schema(self):
+        raise NotImplementedError
+
+    def table_columns(self):
+        """Columns per table, keyed by the same qualified names as `schema()`:
+        `{<schema>.<name>: [col, ...]}`. The bundler's column pruner feeds this to
+        sqlglot as a schema map. Serve-only backends don't implement it."""
+        raise NotImplementedError(f"{type(self).__name__} is serve-only (not bundleable)")
+
+    def export_parquet(self, qualified, columns=None, compression="snappy"):
+        raise NotImplementedError(f"{type(self).__name__} is serve-only (not bundleable)")
+
+    def close(self):
+        pass
+
+
+# Parquet codecs DuckDB writes and reads back. Restricted to an allowlist because
+# the value is interpolated into a COPY statement (it can't be a bind parameter).
+_PARQUET_CODECS = frozenset({"snappy", "zstd", "gzip", "uncompressed"})
+
+
+def parquet_codec(compression):
+    """Validate and normalize a Parquet compression name to a COPY keyword."""
+    c = compression.lower()
+    if c not in _PARQUET_CODECS:
+        raise ValueError(
+            f"unsupported Parquet compression {compression!r}; "
+            f"expected one of {sorted(_PARQUET_CODECS)}")
+    return c
+
+
+class Pool:
+    """A tiny bounded connection pool for network backends. Connections are made
+    lazily up to `size`, then borrowers block for a free one. LIFO so a small
+    working set stays warm."""
+
+    def __init__(self, factory, size=4):
+        self._factory = factory
+        self._free = queue.LifoQueue()
+        self._made = 0
+        self._size = max(1, size)
+        self._lock = threading.Lock()
+
+    @contextmanager
+    def borrow(self):
+        con = self._acquire()
+        ok = False
+        try:
+            yield con
+            ok = True
+        finally:
+            if ok:
+                self._free.put(con)
+            else:
+                try:
+                    con.close()
+                except Exception:
+                    pass
+                with self._lock:
+                    self._made -= 1
+
+    def _acquire(self):
+        try:
+            return self._free.get_nowait()
+        except queue.Empty:
+            pass
+        with self._lock:
+            make = self._made < self._size
+            if make:
+                self._made += 1
+        if make:
+            try:
+                return self._factory()
+            except Exception:
+                with self._lock:
+                    self._made -= 1
+                raise
+        return self._free.get()  # all in use -- block for one
+
+    def close(self):
+        while not self._free.empty():
+            try:
+                self._free.get_nowait().close()
+            except Exception:
+                pass
+
+
+class DBAPIBackend(Backend):
+    """Shared run/query for PEP-249 drivers: translate $name via bind(), borrow a
+    pooled connection, coerce rows. Subclasses set dialect/paramstyle and
+    implement `_connect` (returns a new read-only DBAPI connection), `docs`,
+    `schema`."""
+
+    def __init__(self, *, pool=4):
+        self._pool = Pool(self._connect, size=pool)
+
+    def _connect(self):
+        raise NotImplementedError
+
+    def run(self, sql, args):
+        q, p = bind(sql, args, self.dialect, self.paramstyle)
+        with self._pool.borrow() as con:
+            cur = con.cursor()
+            cur.execute(q, p) if p else cur.execute(q)
+            cols = [d[0] for d in cur.description]
+            rows = cur.fetchall()
+        return cols, [dict(zip(cols, jsonable_row(r))) for r in rows]
+
+    def query(self, sql, limit=2000):
+        with self._pool.borrow() as con:
+            cur = con.cursor()
+            cur.execute(sql)
+            cols = [d[0] for d in cur.description]
+            rows = cur.fetchmany(limit + 1)
+        truncated = len(rows) > limit
+        rows = rows[:limit]
+        return cols, [dict(zip(cols, jsonable_row(r))) for r in rows], truncated
+
+    def close(self):
+        self._pool.close()