duckdb-kernel

DuckDB Kernel

A Jupyter-compatible kernel implemented in Go that provides a SQL execution environment backed by DuckDB.

Features

• SQL execution via embedded DuckDB
• Plain text table result rendering
• Arrow IPC result materialization
• Shared sessions across notebooks
• Meta commands for database exploration
• Compatible with JupyterLab, JupyterHub, and VS Code

Install

From release (recommended)

curl -fsSL https://raw.githubusercontent.com/hugr-lab/duckdb-kernel/main/install.sh | bash

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/hugr-lab/duckdb-kernel/main/install.sh | bash -s v0.1.0

From source

Requires Go 1.26+ and a C compiler (CGo is used by the DuckDB driver).

git clone https://github.com/hugr-lab/duckdb-kernel.git
cd duckdb-kernel
make install

Verify the installation:

jupyter kernelspec list

Usage

1. Start JupyterLab: jupyter lab
2. Create a new notebook and select the DuckDB kernel
3. Execute SQL queries in notebook cells

Example

CREATE TABLE users (id INTEGER, name VARCHAR);
INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob');
SELECT * FROM users;

Meta Commands

Shared Sessions

Set the DUCKDB_SHARED_SESSION environment variable to share a DuckDB session across multiple notebooks:

export DUCKDB_SHARED_SESSION=my-analysis
jupyter lab

Arrow Result Files

Query results are automatically written as Arrow IPC files to:

/tmp/duckdb-kernel/<session-id>/<query-id>.arrow

Cleanup policy: last 5 results retained, files older than 1 hour removed.

License

MIT