hfmsio/dbxlite

Purpose and Entry Points

dbxlite is a browser SQL workbench with a shared UI for local DuckDB, BigQuery, and Snowflake. It runs either against DuckDB-WASM in the browser or a native DuckDB -ui server, while cloud warehouses use browser-facing connectors. Main browser bootstrap: apps/web-client/src/main.tsx, application orchestration: apps/web-client/src/App.tsx. The distributable asset-server CLI is apps/cli/src/cli.js.

Application Composition and State

The React/Vite client composes providers for settings, data sources, tabs, and query state, then renders the explorer/editor/results workspace and dialogs. Contexts carry active-tab and connector/query lifecycle state; Zustand-style stores persist UI, onboarding, AI chat, and source metadata. Key boundaries: apps/web-client/src/contexts/TabContext.tsx, apps/web-client/src/contexts/QueryContext.tsx, apps/web-client/src/stores/dataSourceStore/store.ts.

Query Routing and Lifecycle

useQueryExecution drives user SQL from the editor into the query service. The executor selects an engine/connector mode, manages cancellation and engine-specific lifecycles, and returns structured/streamed results to the grid. This isolates UI from DuckDB, BigQuery, and Snowflake transport differences. Core paths: apps/web-client/src/hooks/useQueryExecution.ts, apps/web-client/src/services/query/query-executor.ts, apps/web-client/src/services/query/connector-registry.ts.

Connector and Engine Layer

The reusable connectors package defines the cross-engine boundary: DuckDB (including HTTP/server mode), BigQuery, and Snowflake connectors plus OAuth/PAT transport and parse workers. Engine detection and lifecycle adapters map browser/server execution modes into those interfaces. Relevant paths: packages/connectors/src/base.ts, packages/connectors/src/duckdb-connector.ts, packages/connectors/src/bigquery-connector.ts, packages/connectors/src/snowflake-connector.ts. BigQuery uses Google APIs directly; Snowflake uses SQL REST API v2 and requires a proxy because of browser CORS/header constraints.

Local DuckDB-WASM and File Access

WASM mode executes DuckDB in a Web Worker through a dedicated adapter. Local files are represented by File System Access handles and virtualized for on-demand reads rather than eagerly copied to memory; remote files rely on DuckDB HTTP access. The browser boundary is material: File System Access API, Web Workers, OPFS, and cross-origin isolation. Paths: packages/duckdb-wasm-adapter/src/index.ts, packages/duckdb-wasm-adapter/src/worker.ts, apps/web-client/src/services/query/file-vfs.ts.

Results, Streaming, and Export

Large result sets are streamed/paginated rather than fully rendered. The virtualized table retrieves pages through query services, supports sorting/selection, and routes exports by engine: native DuckDB COPY, OPFS/download paths, or cloud chunk streaming into DuckDB-backed Parquet writing. Paths: apps/web-client/src/services/streaming-query-service.ts, apps/web-client/src/components/PaginatedTable.tsx, apps/web-client/src/components/table/exporters/index.ts.

Persistence, Credentials, and Optional Integrations

Settings, file handles, and connection metadata are client-side; the storage package provides credential storage, with AES-GCM encryption for supported credential paths. AI is opt-in and provider-pluggable for OpenAI-compatible, Anthropic, Gemini, or warehouse-backed capabilities; consent gates external sends. Gist URL sharing is another external integration. Paths: packages/storage/src/index.ts, apps/web-client/src/services/ai/backend-registry.ts, apps/web-client/src/utils/sharingProviders/providers/gist.ts.

Delivery Modes and Infrastructure

The primary deployment is static assets: Vite builds the client, and nginx serves it with COOP/COEP/CORP headers required for WASM/OPFS behavior. Docker contains no shared query backend. Native server mode instead has DuckDB serve query APIs locally while dbxlite-ui supplies UI assets. Paths: Dockerfile, docker/nginx.conf, apps/cli/scripts/build.js.