How do I install the Query Grapher DB skill?

Run npx skillmds@latest add owid/query-grapher-db in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Query Grapher DB safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Query Grapher DB?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Query Grapher DB free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Query Grapher DB?

owid (@owid) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Query Grapher DB by owid — Agent Skill

Name: Query Grapher DB
Author: owid

Query Grapher DB

Query the grapher MySQL database (local dev, a branch's staging server, or production via the public Datasette) and verify indicators and charts on a staging server. Use when you need to run SQL against grapher, find which charts use an indicator, assess the blast radius of a data fix, or check that a chart/indicator renders correctly on staging-site-<branch>.

owid 5f2f867 2.8 KB Updated Sep 17, 2026

File contents

Querying grapher MySQL and verifying charts on staging

Quick queries (staging)

make query SQL="SELECT COUNT(*) FROM variables WHERE catalogPath IS NULL"

Automatically connects to staging-site-{branch} based on current git branch.

Python (for more control)

from etl.config import OWID_ENV
df = OWID_ENV.read_sql("SELECT * FROM datasets LIMIT 10")

Prefer Python when the SQL contains % (LIKE patterns, JSON_EXTRACT paths) or single-quoted strings — make query re-interprets those via shell + make and breaks unpredictably. Use params={...} for %/quoted values to dodge pymysql's own %-format-string parsing.

OWID_ENV targets your local dev DB even when you're on a branch. To query the branch's staging DB from Python, use OWIDEnv.from_staging('<branch>') (from etl.config import OWIDEnv) — e.g. OWIDEnv.from_staging('my-branch').read_sql(...). Also note make query shells out to the mysql CLI, which may not be installed; if it errors with mysql: command not found, use the Python from_staging(...).read_sql(...) path instead.

Production queries via public Datasette

When you need production data (which charts use an indicator, chart configs, gdoc links) and local/prod MySQL isn't reachable, query the public Datasette over HTTP:

curl -s "https://datasette-public.owid.io/owid.json?sql=<url-encoded SQL>"

chart_dimensions + charts + chart_configs answer "which charts use variable X"; narrative_charts and posts_gdocs_links cover derived charts and article references — together they answer the full "what does this dataset affect?" question when assessing the blast radius of a data fix.

Verifying charts on staging

Indicator data/metadata API: https://api-staging.owid.io/staging-site-<branch>/v1/indicators/<id>.data.json (and .metadata.json). The path prefix is staging-site-<branch>, not the bare branch name — a wrong prefix silently serves data from a different environment instead of 404ing, which looks exactly like "my fix didn't take". When in doubt, grep the staging chart page (http://staging-site-<branch>/grapher/<slug>) for data.json to get the exact URLs it loads.
Rendered chart without a browser: http://staging-site-<branch>/grapher/<slug>.svg returns a server-side render — grep it for axis labels / entity names to verify a fix end-to-end (e.g. grep -oE '>[0-9]+ [a-z]+[^<]*<' to read the y-axis ticks).

---name: query-grapher-dbdescription: Query the grapher MySQL database (local dev, a branch's staging server, or production via the public Datasette) and verify indicators and charts on a staging server. Use when you need to run SQL against grapher, find which charts use an indicator, assess the blast radius of a data fix, or check that a chart/indicator renders correctly on staging-site-<branch>.---# Querying grapher MySQL and verifying charts on staging## Quick queries (staging)```bashmake query SQL="SELECT COUNT(*) FROM variables WHERE catalogPath IS NULL"```Automatically connects to `staging-site-{branch}` based on current git branch.## Python (for more control)```pythonfrom etl.config import OWID_ENVdf = OWID_ENV.read_sql("SELECT * FROM datasets LIMIT 10")```**Prefer Python when the SQL contains `%` (LIKE patterns, JSON_EXTRACT paths) or single-quoted strings — `make query` re-interprets those via shell + make and breaks unpredictably.** Use `params={...}` for `%`/quoted values to dodge pymysql's own `%`-format-string parsing.**`OWID_ENV` targets your local dev DB even when you're on a branch.** To query the branch's staging DB from Python, use `OWIDEnv.from_staging('<branch>')` (`from etl.config import OWIDEnv`) — e.g. `OWIDEnv.from_staging('my-branch').read_sql(...)`. Also note `make query` shells out to the `mysql` CLI, which may not be installed; if it errors with `mysql: command not found`, use the Python `from_staging(...).read_sql(...)` path instead.## Production queries via public DatasetteWhen you need production data (which charts use an indicator, chart configs, gdoc links) and local/prod MySQL isn't reachable, query the public Datasette over HTTP:```bashcurl -s "https://datasette-public.owid.io/owid.json?sql=<url-encoded SQL>"````chart_dimensions` + `charts` + `chart_configs` answer "which charts use variable X"; `narrative_charts` and `posts_gdocs_links` cover derived charts and article references — together they answer the full "what does this dataset affect?" question when assessing the blast radius of a data fix.## Verifying charts on staging- **Indicator data/metadata API**: `https://api-staging.owid.io/staging-site-<branch>/v1/indicators/<id>.data.json` (and `.metadata.json`). The path prefix is `staging-site-<branch>`, **not** the bare branch name — a wrong prefix silently serves data from a different environment instead of 404ing, which looks exactly like "my fix didn't take". When in doubt, grep the staging chart page (`http://staging-site-<branch>/grapher/<slug>`) for `data.json` to get the exact URLs it loads.- **Rendered chart without a browser**: `http://staging-site-<branch>/grapher/<slug>.svg` returns a server-side render — grep it for axis labels / entity names to verify a fix end-to-end (e.g. `grep -oE '>[0-9]+ [a-z]+[^<]*<'` to read the y-axis ticks).

Frequently asked questions