Skip to content

feat(sql): add list_clusters across all bindings - #65

Merged
johnpmitsch merged 4 commits into
mainfrom
sql-list-clusters
Nov 13, 2026
Merged

johnpmitsch merged 4 commits into
mainfrom
sql-list-clusters

Conversation

@johnpmitsch

@johnpmitsch johnpmitsch commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

tl;dr

Adds list_clusters to the SQL Explorer client in Rust, Python, Node.js (listClusters), and Ruby. It calls GET /sql/rest/v1/clusters and returns the clusters a caller can query, each with an id and a display_name.

Impact

  • New method qn.sql.list_clusters() and new exported type SqlCluster in all four packages. Nothing existing changes.
  • The request sends the account API key, the same as query and get_schema.
  • Return shape per language: Rust Vec<SqlCluster>, Python list[SqlCluster], Node.js Array<SqlCluster> (displayName), Ruby Array of hashes (id, display_name).

Where to focus your review

  • npm/sdk.d.ts: SqlCluster is imported at the top of the file as well as re-exported, so listClusters() resolves to Promise<SqlCluster[]> for consumers.
  • Safe to skim: npm/index.d.ts and python/quicknode_sdk/_core/__init__.pyi are generated. Both also pick up an existing gateway_drip doc-comment change that had not been regenerated, and the Python stub has seven whitespace-only lines from the generator.

Decisions & tradeoffs

  1. Bare list return. The API returns a JSON array, and the SDK returns the list as is, with no wrapper struct. To reverse: add a response struct in core and map it in each binding.
  2. Generated files committed as generated. The unrelated doc-comment and whitespace changes come from running the generators on the current source. To reverse: restore those hunks from main.

Technical notes

  • Node exposes the core SqlCluster directly through its napi(object) attribute. It needs no wrapper type because it has no renamed field and no dynamic rows.
  • Ruby registers list_clusters with arity 0, the same as the other methods without parameters.
  • The four SQL example scripts now call list_clusters first and assert that each entry has an ID and a display name and that the script's cluster ID is in the list.

How I verified it

AI: built, tested, and self-reviewed (jreview) by john-pipeline running Claude Code.

Ran:

  • cargo test -p quicknode-sdk --lib passes (289 tests, 3 new: success with the x-api-key header on the wire, API error, decode error)
  • cargo fmt --all -- --check, cargo check --workspace, cargo clippy --workspace --lib --tests -- -D warnings pass
  • cargo clippy -p quicknode-sdk --lib --tests passes with no features and with rust,payments,payments-tempo
  • Python bindings and stubs build; the generated stub has list_clusters and SqlCluster
  • just node-build passes (build and npm test)
  • just ruby-build passes
  • Python, Node.js, and Ruby bindings run against a local mock server: each returns the two-cluster list in the documented shape, maps a 503 to ApiError and bad JSON to DecodeError, and sends the x-api-key header
  • The Node.js SQL example passes against the live API (run by the PR owner): listClusters returns hyperliquid-core-mainnet and solana-mainnet
  • Reviewer: run the Rust, Python, and Ruby SQL example scripts against the live API with a key

Not checked:

  • The Rust, Python, and Ruby example scripts against the live API.

Confidence assessment: how likely is this to affect or break prod

Overall: low risk of breakage, small blast radius if it does, fully reversible by code revert.

Concern Likelihood Why Containment
Existing SQL methods Very low query and get_schema are untouched; their tests pass unchanged Revert the commit
Response shape differs from the live API Low The type matches the documented response (id, display_name); extra fields are ignored by serde A mismatch surfaces as DecodeError with the raw body
Type surface in TypeScript and Python Low Additive export only; builds and stub generation pass Revert the commit

Not verifiable from here:

  • Whether the live endpoint returns fields or statuses other than those documented.

The SQL Explorer API exposes a public cluster catalog at GET clusters.
The request uses the keyless HTTP client so the account API key is not
sent and an SDK without a key can call it.
Adds SqlCluster to the Python and TypeScript exports and the RBS
signature for Ruby. The regenerated type files also pick up an existing
gateway_drip doc-comment change that had not been regenerated.
The four SQL example scripts now list clusters first and assert that
each entry has an id and a display name.
@johnpmitsch
johnpmitsch marked this pull request as ready for review November 13, 2026 14:54
The clusters endpoint returns 401 when the x-api-key header is missing,
so the request now uses the same keyed client as query and get_schema.
@johnpmitsch
johnpmitsch merged commit 60e029e into main Nov 13, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants