metabase-flightsql-driver: Skill for Claude Code

Tutorial generator

Produces a runnable, screenshot-illustrated tutorial under docs/tutorials/, grounded in a live PoC. This is the process proven on iceberg-lakehouse.md — copy its shape.

Each tutorial pairs one use case with the backend that showcases it (see the matrix in docs/tutorials/README.md). Everything is real: you deploy the backend, drive Metabase, and screenshot what actually renders.

Prerequisites

• podman-compose available (this repo uses podman, not docker — the setup scripts auto-detect via CONTAINER_CLI).
• The Playwright MCP tools available.
• Metabase admin login: [email protected] / Metabase123!.

Process (6 phases)

Phase 1 — Choose use case + backend

Pick a row from the matrix (docs/tutorials/README.md). Confirm the backend has a compose profile (docker-compose.<backend>.yaml) and a setup script (scripts/setup_<backend>.py). If not, that PoC has to exist first — model it on docker-compose.dremio.yaml + scripts/setup_dremio.py.

Phase 2 — Deploy + seed + verify

podman-compose -f docker-compose.yaml -f docker-compose.<backend>.yaml up -d <backend>
python scripts/setup_<backend>.py

Verify the backend actually serves data before touching the UI (fresh backends often need the setup re-run — e.g. Dremio's metadata store is ephemeral):

K=$(grep METABASE_API_KEY .env | cut -d= -f2-)
curl -sf -H "x-api-key: $K" -H 'Content-Type: application/json' -X POST \
  http://localhost:3000/api/dataset \
  -d '{"type":"native","database":<DBID>,"native":{"query":"SELECT 1"}}'

Phase 3 — Provision demo content

Create a persistent Metabase connection (the e2e tests delete theirs) and any demo dashboard, using the repo's own helpers so shapes are correct:

import sys; sys.path.insert(0, "scripts")
from metabase_setup import MetabaseConfig, MetabaseClient
c = MetabaseClient(MetabaseConfig()); c.api_key = <API_KEY_FROM_ENV>
# c._request("POST","database",{...})           # create connection
# c.create_native_card(name, db_id, sql, display="bar",
#     visualization_settings={"graph.dimensions":["x"],"graph.metrics":["y"]})
# c.create_dashboard(...) ; c.add_cards_to_dashboard(dash_id, [...])

Chart cards MUST set graph.dimensions/graph.metrics or the card renders "Which fields do you want to use for the X and Y axes?". Scalars and tables need nothing. If a card won't render on the dashboard, drop it — a clean 3-card board beats a broken 4th.