feat(sql): add qn sql for SQL Explorer queries and schema (DX-5876)

[johnpmitsch]

Adds qn sql, wrapping the new quicknode-sdk 0.5 SQL Explorer sub-client. Closes DX-5876.

Two verbs:

• qn sql query runs a read-only query against a cluster.
• qn sql schema <CLUSTER_ID> shows a cluster's table schema.

qn sql query

The SQL can be passed inline, from a file (--file <path>), or from stdin (--file -) — mutually exclusive, exactly one required. Rows go to stdout; query stats print to stderr as a note, with a truncation hint when the 1000-row-per-request cap is hit. The query does not auto-retry (it consumes credits, so a retried query would re-bill).

$ qn sql query "SELECT toDateTime(block_time) AS time, action_type, user
    FROM hyperliquid_system_actions
    WHERE block_time >= now() - INTERVAL 1 DAY
    ORDER BY block_time DESC LIMIT 10000" --cluster-id hyperliquid-core-mainnet
✓ 10000 rows · 146 credits · 0.005s · 18517 matched (use LIMIT/OFFSET to page)
TIME                 ACTION_TYPE                   USER
2026-06-25 03:12:12  SystemSendAssetAction         0xaaa...
2026-06-25 03:12:12  SystemSpotSendAction          0xbbb...
...

Rendering: headers come from the response meta (so an empty result set still prints its columns); scalars render unquoted, null renders as —, and nested arrays/objects fall back to compact JSON. Structured formats keep the full response:

$ qn sql query "..." --cluster-id hyperliquid-core-mainnet -o json
{
  "meta": [ { "name": "time", "type": "DateTime('UTC')" }, ... ],
  "data": [ { "time": "...", "action_type": "...", "user": "0x..." }, ... ],
  "rows": 10000,
  "rows_before_limit_at_least": 18517,
  "statistics": { "elapsed": 0.005, "rows_read": ..., "bytes_read": ... },
  "credits": 146
}

qn sql schema

Prints each table as a block: engine, row count, partition/sorting keys, then a COLUMN/TYPE sub-table. Retries like other reads.

$ qn sql schema hyperliquid-core-mainnet
Hyperliquid (HyperCore) · hyperliquid-core-mainnet · 46 tables

hyperliquid_agents (SharedReplacingMergeTree, 3336219565 rows)
  partition: toYYYYMM(snapshot_time)
  sorting: block_number, agent
COLUMN         TYPE
agent          FixedString(42)
block_number   UInt64
...

Implementation notes

• Bumps quicknode-sdk 0.4 → 0.5.
• Routes the SQL base path (/sql/rest/v1/) under the --base-url override in context.rs so integration tests hit the mock, not production — same pattern as the other sub-clients.
• New src/commands/sql/{mod.rs, render.rs}; wired through cli.rs and commands/mod.rs.
• Updates the README and the embedded agent context catalog (and notes the query no-retry behavior).

Tests

• tests/sql.rs: 8 integration tests — camelCase clusterId wire body, --file read, missing-file / arg-group / inline+file conflict (exit 1), API error (exit 2), schema happy path and 404.
• tests/table_snapshots.rs: 2 subprocess snapshots covering visible table output (unquoted scalars + null → —; nested schema blocks including an empty-metadata view).
• 3 unit tests for the cell-rendering helper.

cargo test, cargo clippy --all-targets -D warnings, cargo fmt --check, and cargo build --release all pass.