DuckDB UI and Harlequin
Both tools run DuckDB on your machine and need no server: the DuckDB UI is a notebook-style SQL editor in your browser, and Harlequin is a SQL IDE in the terminal. Start either with the same init script, and the records view from DuckDB is ready to query.
| You want | Use |
|---|---|
| A browser editor with notebooks, a schema browser and column summaries | The DuckDB UI |
| An editor in the terminal, for example over SSH | Harlequin |
| Harlequin against a warehouse you already run | A Harlequin adapter for Trino, PostgreSQL or BigQuery |
We started the DuckDB UI server with the init script below (DuckDB CLI 2.0.0) and ran queries through Harlequin's DuckDB adapter with the same script, against our own sample data. We did not click through the UI in a browser or drive Harlequin's terminal interface; those steps follow DuckDB's UI documentation and Harlequin's --help.
The init script
Save the statements for your destination from DuckDB in a file, for example s2b-init.sql. For an Amazon S3 destination:
INSTALL httpfs; LOAD httpfs;
CREATE SECRET IF NOT EXISTS s2b_bucket (
TYPE s3, KEY_ID '<access_key_id>', SECRET '<secret_access_key>', REGION '<region>');
CREATE OR REPLACE VIEW records AS
SELECT * FROM read_json(
's3://<bucket>/<prefix>/s2b/stream=*/date=*/hour=*/*.ndjson.gz',
format = 'newline_delimited',
hive_partitioning = true,
columns = {v: 'INTEGER', delivery_batch_id: 'VARCHAR', batch_id: 'VARCHAR',
received_at: 'TIMESTAMPTZ', signal: 'VARCHAR',
resource: 'JSON', scope: 'JSON', data: 'JSON'});
Use a storage key that can only read the bucket, or PROVIDER credential_chain to use your AWS profile. For a table destination, use the ATTACH and view for your catalog instead; DuckLake catalogs need DuckDB 2.0 or later.
DuckDB UI
The UI is a DuckDB extension. Start the DuckDB CLI with the init script and the -ui flag:
duckdb -init s2b-init.sql -ui
DuckDB runs the script, starts a local web server on port 4213, and opens it in your browser. The UI runs on the same DuckDB instance as the CLI, so the records view and the secret are already there. Run the example queries in a notebook cell.
From a session that is already running, CALL start_ui(); does the same, and CALL start_ui_server(); starts the server without opening a browser. Change the port with SET ui_local_port = <port>; before starting it.
Without -init, the DuckDB CLI runs ~/.duckdbrc at startup, so you can put the statements there to have them in every session.
Things to know:
- The UI stores notebooks in DuckDB tables, so it does not start on a database opened read-only. Start it on an in-memory or writable database and
ATTACH '<file>.duckdb' (READ_ONLY)if you want a read-only file. - Queries run locally. The server loads the UI's web assets from
ui.duckdb.org, so the browser needs internet access; your data is not sent there. Signing in to MotherDuck in the UI is optional. - The UI is not available for macOS on Intel (
osx_amd64) or Windows on ARM.
Harlequin
Install Harlequin with uv tool install harlequin or pipx install harlequin. It ships with a DuckDB adapter, and uses the duckdb Python package installed with it.
harlequin --init-path s2b-init.sql
With no database argument, Harlequin opens an in-memory database. To work in a file instead, pass its path: harlequin s2b.duckdb --init-path s2b-init.sql. Without --init-path, Harlequin runs ~/.duckdbrc, like the DuckDB CLI; --no-init skips it. Add --read-only to open a database file read-only, and keep only the CREATE SECRET in the script in that case, since views cannot be created on a read-only database.
Write the example queries in the editor and run them with Ctrl+Enter, or Ctrl+J in terminals that do not pass Ctrl+Enter through. Results can be exported to CSV, Parquet or JSON from the results pane.
Other Harlequin adapters
Harlequin connects to other engines through adapter packages, installed as extras:
uv tool install 'harlequin[trino,postgres,bigquery]'
| Adapter | Example | Tables from |
|---|---|---|
| Trino | harlequin -a trino -h <host> -p 443 -U <user> --password <password> --require_auth password --sslcert <ca_bundle.pem> --catalog <catalog> --schema <schema> | Trino |
| PostgreSQL | harlequin -a postgres -h <host> -p 5432 -U <user> --password <password> -d <dbname> | PostgreSQL |
| BigQuery | harlequin -a bigquery --project <project_id>, with application default credentials | BigQuery |
With --require_auth password, the Trino adapter connects over HTTPS and verifies the server certificate only when --sslcert names a CA bundle; without it, the certificate is not checked. Run harlequin --help after installing to see each adapter's options. Store repeated options in a profile in .harlequin.toml (harlequin --config starts a wizard) instead of typing passwords on the command line.
Notes
- Both tools keep nothing between sessions unless you use a database file; the init script recreates the secret and view each time.
- A view over bucket objects reads the bucket on every query. Filter on
dateto read fewer objects. - The init script holds a storage key in plain text. Keep it out of version control, or use
PROVIDER credential_chain.