Skip to main content

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 wantUse
A browser editor with notebooks, a schema browser and column summariesThe DuckDB UI
An editor in the terminal, for example over SSHHarlequin
Harlequin against a warehouse you already runA Harlequin adapter for Trino, PostgreSQL or BigQuery
note

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]'
AdapterExampleTables from
Trinoharlequin -a trino -h <host> -p 443 -U <user> --password <password> --require_auth password --sslcert <ca_bundle.pem> --catalog <catalog> --schema <schema>Trino
PostgreSQLharlequin -a postgres -h <host> -p 5432 -U <user> --password <password> -d <dbname>PostgreSQL
BigQueryharlequin -a bigquery --project <project_id>, with application default credentialsBigQuery

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 date to read fewer objects.
  • The init script holds a storage key in plain text. Keep it out of version control, or use PROVIDER credential_chain.