DBeagle Design

April 11, 2026 · View on GitHub

Scope

DBeagle is a read-only VS Code extension for querying and inspecting SQL data from inside VS Code. V1 is intentionally narrow:

  • Five shipped driver implementations: Trino, PostgreSQL, MySQL, SQL Server, and Vertica
  • Shared connection storage, driver IDs, and dialect wiring are generalized for future engines. Trino, PostgreSQL, MySQL, SQL Server, and Vertica are shipped today; additional engines still build on the same shared model.
  • Six SQL dialect modes in the parser: trino, postgres, mysql, mssql, vertica, and ansi
  • One result surface: grid first, charting after finalization
  • No backward-compatibility shims, compatibility aliases, or runtime fallback data paths

Anything outside that surface belongs in backlog, not in the runtime.

Runtime Architecture

VS Code extension host (TypeScript)
  ├─ connection management, driver descriptors, and secrets
  ├─ query planning / read-only checks / execution orchestration
  ├─ result-session lifecycle and webview messaging
  ├─ Trino driver integration
  ├─ native addon loader (exact platform binary)
  └─ SQL parser loader (exact dist/sql-parser bundle)

Native addon (Rust via napi-rs)
  ├─ streamed result ingestion
  ├─ paging, filtering, sorting, counting
  ├─ chart data shaping
  └─ CSV / JSON export

SQL parser crate (Rust -> wasm-pack bundle)
  ├─ statement splitting
  ├─ parsing
  ├─ read-only validation
  ├─ completion context
  └─ formatting

Webviews
  ├─ connection form
  └─ results grid / chart

Shared Namespace Model

DBeagle currently standardizes database metadata as catalog -> schema -> table in the shared tree, completion snapshot, and schema-scope model.

  • Trino maps directly to that shape.
  • PostgreSQL maps the connected database into the shared catalog slot and keeps schemas as-is.
  • SQL Server maps database and schema directly into the shared model.
  • Vertica follows the same database/schema shape.
  • MySQL is the outlier because databases and schemas are effectively the same namespace. The shared model stays in place for now, and the dedicated MySQL phase will finalize whether that should surface as a synthetic level or a collapsed tree experience.

This decision keeps the current metadata APIs stable while making the driver-specific mapping explicit instead of implicit in scattered call sites.

Result Flow

  1. Query text is selected or derived from the active SQL editor.
  2. The parser splits statements and enforces read-only execution.
  3. The active runtime driver streams result pages.
  4. The extension appends each page into the native result store.
  5. The result session publishes incremental state to the webview.
  6. Once the configured dbeagle.resultGrid.maxRows limit is reached, ingestion stops, the statement is marked truncated, and the session completes with an explicit status message.
  7. After finalization, the session enables full paging, filtering, sorting, charting, and export interactions.

Session Model

  • Result sessions are keyed by document URI.
  • Closing a document disposes any non-detached session for that document.
  • Detached panels keep the session alive until the panel closes.
  • Query cancellation is explicit and routed through the owning session.

This keeps result memory bounded and prevents abandoned editor sessions from accumulating in the extension host.

Security and Failure Model

  • Native binaries are loaded from the canonical native/<platform-binary>.node path only.
  • The SQL parser is loaded from dist/sql-parser/sql_parser.js only.
  • Passwords stay in VS Code SecretStorage; connection definitions stay in configuration.
  • Webviews use a restrictive CSP and escape rendered text before injecting it into HTML.
  • Runtime failures fail loudly with actionable errors.
  • V1 does not keep compatibility-mode readers, reconnect retries, silent empty-metadata snapshots, or static/manual runtime data paths.

Source Layout

src/
  connectionForm/      connection form host/session orchestration, message validation, and action execution
  drivers/             driver contracts, descriptors, Trino driver, ingest helpers, Trino runtime/execution modules
  managers/            connection and driver managers
  native/              exact native loader and TS-native adapter
  providers/           tree view, gutters, editor-facing providers
  query/               execution orchestration, diagnostics, history, parameter scope/state helpers, execution runner
  results/             result-session state, chart/view helpers, webview host, message handling
  sql/                 parser types and module loader

webview/
  connection/          form state, validation, rendering, DOM bridge
  results/             result-grid/chart renderers, state helpers, events, styles

native/src/
  result_store.rs
  result_store/
    view.rs            paging, sorting, filtering, view materialization
    chart.rs           chart data shaping
    export.rs          CSV / JSON export helpers
  result_store_tests.rs
  types.rs             serde/napi payload types

crates/sql-parser/src/
  parse.rs
  complete.rs
  validate.rs
  format.rs
  dialect.rs

V1 Boundaries

  • No released data migration system exists yet.
  • No extra drivers beyond Trino, PostgreSQL, MySQL, SQL Server, and Vertica are supported in the shipped runtime.
  • No compatibility aliases like presto.
  • No legacy native binding name resolution.
  • No manual metadata or hardcoded query results in production paths.
  • Released VSIX artifacts are currently built for darwin-x64, linux-x64, and win32-x64.