duckdb/duckdb-ui

DuckDB UI Extension

A DuckDB extension providing a browser-based user interface.

This repository contains both the extension, implemented in C++, and some packages used by the user interface, implemented in TypeScript.

While most of the user interface code is not yet publicly available, more of it will added here over time.

Extension

The primary structure of this repository is based on the DuckDB extension template.

To build the extension:

make

This will create the following binaries:

./build/release/duckdb                              # DuckDB shell with UI extension
./build/release/test/unittest                       # Test runner
./build/release/extension/ui/ui.duckdb_extension    # Loadable extension binary

• duckdb is the binary for the duckdb shell with the extension code automatically loaded.
• unittest is the test runner of duckdb. Again, the extension is already linked into the binary.
• ui.duckdb_extension is the loadable binary as it would be distributed.

To run the extension code, simply start the shell with ./build/release/duckdb.

To start the UI from the command line:

./build/release/duckdb -ui

To start the UI from SQL:

call start_ui();

For more usage details, see the documentation.

User Interface Packages

Some packages used by the browser-based user interface can be found in the ts directory.

See the README in that directory for details.

Architectural Overview

The extension starts an HTTP server that both serves the UI assets (HTML, JavaScript, etc.) and handles requests to run SQL and perform other DuckDB operations.

The server proxies requests for UI assets and fetches them from a remote server. By default, this is https://ui.duckdb.org, but it can be overridden.

The server also exposes a number of HTTP endpoints for performing DuckDB operations. These include running SQL, interrupting runs, tokenizing SQL text, and receiving events (such as catalog updates). For details, see the HttpServer::Run method in http_server.cpp.

The UI uses the TypeScript package duckdb-ui-client for communicating with the server. See the DuckDBUIClient and DuckDBUIClientConnection classes exposed by this package for details.