Skip to content

feat: support Symbol.asyncDispose on client, session, and operation - #586

Merged
vuanhphung merged 6 commits into
mainfrom
feat/issue-331-async-dispose
Nov 12, 2026
Merged

vuanhphung merged 6 commits into
mainfrom
feat/issue-331-async-dispose

Conversation

@vuanhphung

@vuanhphung vuanhphung commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Adds Symbol.asyncDispose to DBSQLClient, DBSQLSession, and DBSQLOperation, so await using calls their existing close() methods on scope exit. This covers both the Thrift and kernel backends and preserves the existing close and cancellation behavior.

Public interfaces and factory return types remain compatible with existing implementations, mocks, and subclasses. In TypeScript, use the exported asyncDisposable() helper for interface-typed results:

import { DBSQLClient, asyncDisposable } from '@databricks/sql';

async function main() {
  await using client = new DBSQLClient();
  await client.connect({ host, path, token });
  await using session = asyncDisposable(await client.openSession());
  await using operation = asyncDisposable(await session.executeStatement('SELECT 1'));
}

The published declarations include a Symbol.asyncDispose shim for consumers without esnext.disposable. The README explains the runtime/compiler requirements and how disposal errors propagate.

Validation: 366 focused unit tests pass, including consumer declaration tests, plus build, type-check, lint, and formatting. Live warehouse tests were not rerun.

Fixes #331.

DBSQLClient, DBSQLSession, and DBSQLOperation (and the IDBSQLClient,
IDBSQLSession, and IOperation interfaces) gain [Symbol.asyncDispose](),
which delegates to close(), so `await using` works on both backends.
Disposing an already-closed object is a no-op.

The published typings declare SymbolConstructor.asyncDispose themselves,
so consumers don't need TypeScript's esnext.disposable lib or a recent
@types/node.

Fixes #331

Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No issues identified by the review bot.

@vuanhphung

Copy link
Copy Markdown
Collaborator Author

@bot Please mention adding esnext.disposable to compilerOptions.lib when the consumer’s typings don’t already provide disposable declarations. Otherwise, the documented example can fail even with TypeScript 5.2+.

@github-actions

Copy link
Copy Markdown

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

@peco-engineer-bot

Copy link
Copy Markdown
Contributor

Pushed ec3a551 to feat/issue-331-async-dispose addressing your request.

Started from 82b6e7b. I added a note to the README's "Automatic cleanup with await using" section. It says TypeScript needs the disposable declarations, such as the global AsyncDisposable type, to compile await using. If the consumer's typings don't already provide them, they should add "esnext.disposable" (or "esnext") to compilerOptions.lib in tsconfig.json. Otherwise the example can fail to compile even with TypeScript 5.2+. Only the README changed. npm run prettier passes. I didn't run the build or tests because no code changed.

peco-engineer-bot Bot added a commit that referenced this pull request Nov 12, 2026
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No issues identified by the review bot.

@github-actions

Copy link
Copy Markdown

Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase (git rebase -i main).

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No issues identified by the review bot.

vuanhphung and others added 2 commits November 12, 2026 17:02
Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>
Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No issues identified by the review bot.

@vuanhphung

Copy link
Copy Markdown
Collaborator Author

@bot

  1. High — Attempt remaining cleanup after an operation close fails — DBSQLSession.ts:373

With the README’s nested await using example, an operation whose close always rejects is retried three times, while session/backend closure and client telemetry release are skipped. Can we continue closing other resources and always attempt parent cleanup, then report the collected failures? Please add a regression test for this path. If deferred, qualify the README’s cleanup guarantee and mention SuppressedError when both the body and disposal fail.

  1. Medium — Release cancelled operations during disposal — DBSQLOperation.test.ts:433

This test enshrines disposal after cancellation as a no-op. Cancellation already removes the operation from its session’s collection, and closeInternal() skips cancelled operations, so neither disposal nor session cleanup invokes the operation
backend’s close. Can we allow closing cancelled operations and retain them for cleanup until closed? The test should verify that cancel followed by disposal releases the backend handle exactly once.

Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
@peco-engineer-bot

Copy link
Copy Markdown
Contributor

Pushed ca5fa37 to feat/issue-331-async-dispose addressing your request.

Started from 02233d7. Fixed both items.
1: CloseableCollection.closeAll(), DBSQLSession.close() and DBSQLClient.close() now try every cleanup step, then rethrow: one failure unchanged, several as AggregateError. A failing operation is tried twice (its own disposal, then the session), not three times, and the session, backend, feature flags and telemetry are released.
2: Cancelling keeps the operation in its session, and close/dispose after cancel releases the backend once. Updated the 2 tests that relied on the old behaviour; added regression tests for both paths (Thrift and kernel). README and CHANGELOG updated, including SuppressedError.
Build, npm test (1578 passing), type-check and prettier pass. Lint couldn't run: the runner can't load `air

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No issues identified by the review bot.

@vuanhphung

Copy link
Copy Markdown
Collaborator Author

@bot
Please update PR #586 so async disposal is additive for existing interface implementers:

• Restore IDBSQLClient, IDBSQLSession, and IOperation to their original contracts. Keep Symbol.asyncDispose on the concrete classes.

• Give concrete class methods disposable return types: connect(): Promise, openSession(): Promise, and operation factories—including metadata methods— returning Promise. Update private staging helpers as needed.

• Keep the symbol declaration shim reachable from the emitted class declarations. Supported Node versions already provide the runtime symbol.

• Add consumer type tests against emitted dist declarations: legacy interface implementations/mocks still compile, explicit disposal works without esnext.disposable, and an await using client → session → operation chain compiles with it.

• Update the CHANGELOG to remove the requirement for custom interface implementations to add disposal.

Retain the cleanup-failure and cancellation fixes. Check subclass override compatibility before narrowing existing class methods; if that introduces another source break, use an additive disposable factory/helper instead.

Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>
@peco-engineer-bot

Copy link
Copy Markdown
Contributor

Pushed 2b82769 to feat/issue-331-async-dispose addressing your request.

Started from ca5fa37. IDBSQLClient/IDBSQLSession/IOperation are back to their original contracts; the concrete classes keep Symbol.asyncDispose and now import the shim themselves. I didn't narrow the return types: a test showed it breaks existing subclasses (TS2416). So I added an exported asyncDisposable() helper. New consumer type tests compile in-memory fixtures against freshly emitted declarations: legacy implementations, mocks and subclasses, and explicit disposal, with and without esnext.disposable, plus an await using chain with it. CHANGELOG and README are updated; the cleanup and cancel fixes are kept. npm test (1596), type-check and prettier pass. Lint failed before checking any file: ESLint picked up an .eslintrc in the folder above the check

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No issues identified by the review bot.

Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No issues identified by the review bot.

@vuanhphung
vuanhphung added this pull request to the merge queue Nov 12, 2026
Merged via the queue into main with commit 357cb49 Nov 12, 2026
23 checks passed
@vuanhphung
vuanhphung deleted the feat/issue-331-async-dispose branch November 13, 2026 07:31

This branch was previously deployed

1 inactive deployment
azure-prod — 78aea2ef Deployed Nov 12, 2026 by vuanhphung via e2e-test (22.23.4, 22_23_4) #1953
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.

Request for enhancement: Support Symbol.asyncDispose for session and operation

1 participant