eric/duckdb-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme (#11)

Browse Source 
* update readme

* add docs & README to main workflow ignore paths
This commit is contained in:
Jeff Raymakers
2025-06-13 12:12:03 -07:00
committed by GitHub
parent 0edb52054a
commit 13cb9c5ab9
2 changed files with 31 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
README.md
View File

@@ -1,24 +1,14 @@
# duckdb-ui
# DuckDB UI Extension
This extension provides a user interface for DuckDB, allowing you to interact with DuckDB through a web-based interface. This repository is based on https://github.com/duckdb/extension-template, check it out if you want to build and ship your own DuckDB extension.
A [DuckDB extension](https://duckdb.org/docs/stable/core_extensions/ui.html) 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.
## Building
While most of the user interface code is not yet publicly available, more of it will added here over time.
### Managing dependencies
## Extension
DuckDB extensions uses VCPKG for dependency management. Enabling VCPKG is very simple: follow the [installation instructions](https://vcpkg.io/en/getting-started) or just run the following:
```shell
git clone https://github.com/Microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_TOOLCHAIN_PATH=`pwd`/vcpkg/scripts/buildsystems/vcpkg.cmake
```
Note: VCPKG is only required for extensions that want to rely on it for dependency management. If you want to develop an extension without dependencies, or want to do your own dependency management, just skip this step. Note that the example extension uses VCPKG to build with a dependency for instructive purposes, so when skipping this step the build may not work without removing the dependency.
### Build steps
The primary structure of this repository is based on the [DuckDB extension template](https://github.com/duckdb/extension-template).
To build the extension:
@@ -38,66 +28,38 @@ This will create the following binaries:
- `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.
## Running the extension
To run the extension code, simply start the shell with `./build/release/duckdb`.
Now we can use the features from the extension directly in DuckDB. The template contains a single scalar function `ui()` that takes a string arguments and returns a string:
To start the UI from the command line:
```
D select ui('Jane') as result;
┌───────────────┐
│ result │
│ varchar │
├───────────────┤
│ Ui Jane 🐥 │
└───────────────┘
./build/release/duckdb -ui
```
## Running the tests
Different tests can be created for DuckDB extensions. The primary way of testing DuckDB extensions should be the SQL tests in `./test/sql`. These SQL tests can be run using:
```sh
make test
To start the UI from SQL:
```
call start_ui();
```
### Installing the deployed binaries
For more usage details, see the [documentation](https://duckdb.org/docs/stable/core_extensions/ui.html).
To install your extension binaries from S3, you will need to do two things. Firstly, DuckDB should be launched with the
`allow_unsigned_extensions` option set to true. How to set this will depend on the client you're using. Some examples:
## User Interface Packages
CLI:
Some packages used by the browser-based user interface can be found in the `ts` directory.
```shell
duckdb -unsigned
```
See the [README](ts/README.md) in that directory for details.
Python:
## Architectural Overview
```python
con = duckdb.connect(':memory:', config={'allow_unsigned_extensions' : 'true'})
```
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.
NodeJS:
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](https://duckdb.org/docs/stable/core_extensions/ui.html#remote-url).
```js
db = new duckdb.Database(':memory:', {"allow_unsigned_extensions": "true"});
```
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](src/http_server.cpp).
Secondly, you will need to set the repository endpoint in DuckDB to the HTTP url of your bucket + version of the extension
you want to install. To do this run the following SQL query in DuckDB:
```sql
SET custom_extension_repository='bucket.s3.eu-west-1.amazonaws.com/<your_extension_name>/latest';
```
Note that the `/latest` path will allow you to install the latest extension version available for your current version of
DuckDB. To specify a specific version, you can pass the version instead.
After running these steps, you can install and load your extension using the regular INSTALL/LOAD commands in DuckDB:
```sql
INSTALL ui
LOAD ui
```
The UI uses the TypeScript package [duckdb-ui-client](ts/pkgs/duckdb-ui-client/package.json) for communicating with the server.
See the [DuckDBUIClient](ts/pkgs/duckdb-ui-client/src/client/classes/DuckDBUIClient.ts) and [DuckDBUIClientConnection](ts/pkgs/duckdb-ui-client/src/client/classes/DuckDBUIClientConnection.ts) classes exposed by this package for details.