[jiayuasu]

Over a quota, the API can give a keyed session to a connection under another key (the quota fallback). Only that connection is told: the session's own connection still reports its own session_key and no session_fallback. So the check the README recommended before stop_session() (a matching key) can pass while another client is using the session, and the stop cuts that client off. This came up in review of wherobots/wherobots-dbt#82, which stops a dbt run's session when dbt exits.

studio-backend now lets a request keep its session to its key (sessionKeyExclusive, wherobots/studio-backend#3167, Linear WBC-1697): the API never gives that session to another key, even over a quota, and stores the flag with the session. It's on staging and goes out with the next production release. This PR lets the driver ask for it and report it, and bumps the version to 0.32.0 for release.

Changes

• connect(session_key_exclusive=True) sends sessionKeyExclusive: true in the request body, next to sessionKey.
  • It requires a session_key. Without one, connect() raises ValueError before any request, as the API would refuse it.
  • Without the flag, the request body is unchanged.
• Connection.session_key_exclusive says whether the API keeps the session to its key. connect() reads it from apiPayload.sessionKeyExclusive in the session record it already polls until READY, as it does session_key, so it costs no extra request.
  • It's True only when the API stores a JSON true. An API without the change ignores the request's flag and stores nothing, so it's False there, and for a connect_direct() connection.
• connect_direct() passes it through to Connection.
• README: the "Stopping the SQL session" example now asks for session_key_exclusive=True and checks both session_key and session_key_exclusive before stopping. The parameter list documents the new argument.
• Version: 0.32.0, in its own commit.

Verification

• Unit tests: 10 new cases, 337 pass in total. Every new case failed before the change, except the two checking that a request without the flag is unchanged. They cover:
  • the flag in the body when asked for, and its absence otherwise, with or without a key;
  • ValueError without a key, with no request sent;
  • the stored flag reaching the connection: true, false, the string "true", a missing field, no stored request;
  • the flag reaching the real Connection through connect_direct(), and the property's default.
• pre-commit run --all-files passes, and uv lock --check passes after the bump.
• Live on 2026-11-06, micro in aws-us-west-2, through wherobots-dbt with this branch installed (a 4-model run with threads: 4):
  • Staging, which has the API change: the session was stored with sessionKey: dbt-<invocation id> and sessionKeyExclusive: true, session_key_exclusive was True, and stop_session() stopped it. Its status is now DESTROYED.
  • Production, which doesn't have the change yet: the API accepted the request with the extra field, and session_key_exclusive was False, so the caller left the session running.

Compatibility

• The new argument comes last and defaults to False, so existing calls behave as before.
• An API without the change ignores the field: it doesn't fail the request, and the property reports False.

[salty-hambot]

Reviewed by Salty Hambot 🤖🧂 at dad6d07

No issues found.
_{💰 $0.1101 · 133.9k in / 1.4k out tokens · ⏱️ 16s · us.openai.gpt-6-sol high, prompt coverage-v1
💬 To request a re-review, comment @salty-hambot review}

[ClayMav]

nit: over a quota the API can also hand this connection a plain session under its own key (test_key_exclusive_request_over_quota_is_told_it_got_its_keys_plain_session in studio-backend#3167). session_fallback is "quota" and session_key equals the caller's key, which also contradicts "It equals your key when the API kept the run on its own sessions" in the stopping section. Maybe: "Over a quota, the connection itself can still be given a shared session, even one under its own key; session_fallback says so and session_key_exclusive is False."

[jiayuasu]

Fixed in dad6d07. The session_key_exclusive bullet now uses your wording, and the stopping section no longer says a matching key means the run's own session. I also fixed session_fallback's docstring and the fallback warning, which said the session was always another key's.