convex-duckdb-sync
v0.0.2
Published
Sync a local DuckDB mirror of Convex data for ad-hoc analytics.
Downloads
312
Readme
convex-duckdb-sync
CLI client for syncing Convex data into a local DuckDB database through a Convex DuckDB proxy.
npx convex-duckdb-sync install
npx convex-duckdb-sync status
npx convex-duckdb-sync refresh
npx convex-duckdb-sync refresh --fullConfig
The CLI reads only:
.convex-duckdb/config.jsonCreate it with:
npx convex-duckdb-sync installRequired keys:
| Key | Purpose |
| --- | --- |
| CONVEX_DUCKDB_PROXY_URL | Mirror proxy URL |
| CONVEX_DUCKDB_ACCESS_TOKEN | Bearer token for mirror data routes |
The CLI does not load environment variables or .env files.
Sync behavior
- Incremental sync fetches document deltas from
/api/document_deltas. - Full restore downloads collection snapshots through
/api/json_schemasand/api/list_snapshot, then builds.convex-duckdb/data.duckdb. - If the mirror retention window expired, refresh performs a full restore automatically.
Query with the DuckDB CLI:
duckdb -readonly .convex-duckdb/data.duckdb -markdown <<< "SELECT count(*) FROM table_name;"See the root README for proxy setup and skills/convex-duckdb-sync for reusable agent query patterns.
