Quack Kernels for Jupyter

0.3.9 · active · verified Sat Apr 11

quack-kernels provides Jupyter Kernels for DuckDB, enabling users to interact with DuckDB databases directly from Jupyter notebooks using either SQL or Python. It currently stands at version 0.3.9 and is actively maintained with releases tied to DuckDB and Jupyter ecosystem updates.

Warnings

gotcha DuckDB version compatibility: `quack-kernels` is closely tied to specific `duckdb` versions. Ensure your `duckdb` installation is compatible with the `quack-kernels` version to avoid unexpected behavior or errors.
Fix: Always install `quack-kernels` in a fresh environment or ensure your `duckdb` version aligns with the `quack-kernels` requirements. If issues arise, try upgrading/downgrading `duckdb` or `quack-kernels` to a known working pair.
gotcha Kernel not appearing in Jupyter: After installation, if the 'DuckDB SQL' or 'DuckDB Python' kernels do not appear in Jupyter, the kernelspecs might not have been installed correctly.
Fix: Run `python -m ipykernel install --user --name duckdb_sql --display-name 'DuckDB SQL'` and `python -m ipykernel install --user --name duckdb_python --display-name 'DuckDB Python'` (though `quack-kernels` handles this, manual intervention might be needed for unusual environments), or reinstall `quack-kernels` and restart Jupyter.
gotcha In-memory database persistence: When using `duckdb.connect(':memory:')`, the database and all its data are lost if the kernel is restarted or the notebook session ends. This is a common pitfall for data analysis.
Fix: For persistent data, connect to a file-based DuckDB database: `con = duckdb.connect(database='my_database.duckdb')`. The file will persist across kernel restarts and sessions.
gotcha Misunderstanding kernel purpose (SQL vs. Python): Users sometimes try to run Python code in the 'DuckDB SQL' kernel or raw SQL in the 'DuckDB Python' kernel without magic commands.
Fix: Select the 'DuckDB Python' kernel for general Python code that uses `duckdb` module. Select the 'DuckDB SQL' kernel for running raw SQL queries directly in cells. Use Jupyter magic commands (`%%sql` etc.) in Python notebooks if you need to mix languages.

Install

pip install quack-kernels Install core library and kernels

Imports

DuckDBSQLKernel
```
from quack_kernels.duckdb_sql import DuckDBSQLKernel
```
Primarily used for programmatic kernel management or customization. End-users typically interact by selecting kernels in Jupyter, not through direct Python imports in their notebooks.
DuckDBPythonKernel
```
from quack_kernels.duckdb_python import DuckDBPythonKernel
```
Similar to DuckDBSQLKernel, this is for programmatic interaction; standard usage is via Jupyter kernel selection.

Quickstart

After installing with `pip install quack-kernels`, launch Jupyter Lab or Notebook (`jupyter lab`). Create a new notebook and select either the 'DuckDB SQL' or 'DuckDB Python' kernel. The provided Python code demonstrates interaction with DuckDB using the 'DuckDB Python' kernel, where direct `duckdb` module calls are supported.

import duckdb
import pandas as pd

# This code runs within a Jupyter notebook using the 'DuckDB Python' kernel.
# The 'quack-kernels' library provides the infrastructure for this.

# Connect to an in-memory DuckDB database
con = duckdb.connect(database=':memory:', read_only=False)

# Create a table and insert data using SQL
con.execute("CREATE TABLE my_data (id INTEGER, name VARCHAR);")
con.execute("INSERT INTO my_data VALUES (1, 'Alice'), (2, 'Bob'), (3, 'Charlie');")

# Query the table and fetch results into a pandas DataFrame
result_df = con.execute("SELECT * FROM my_data WHERE id > 1;").fetchdf()

print("Fetched data from DuckDB (as pandas DataFrame):")
print(result_df)

# Close the connection (important for file-based DBs, optional for :memory:)
con.close()

view raw JSON →