A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
MotherDuck
MotherDuck is a cloud-based data warehouse that combines the power of DuckDB with the scalability of the cloud. This guide will help you integrate MotherDuck with marimo.
1. Connecting to MotherDuck
To use MotherDuck as a data source, you'll need to install the marimo[sql] Python package.
/// tab | install with pip
pip install "marimo[sql]"
///
/// tab | install with uv
uv add "marimo[sql]"
///
/// tab | install with conda
conda install -c conda-forge marimo duckdb polars
///
To connect to MotherDuck, import duckdb and ATTACH your MotherDuck database.
Using MotherDuck
1. Connecting and Database Discovery
/// tab | SQL
ATTACH IF NOT EXISTS 'md:my_db'
///
/// tab | Python
import duckdb
# Connect to MotherDuck
duckdb.sql("ATTACH IF NOT EXISTS 'md:my_db'")
///
You will be prompted to authenticate with MotherDuck when you run the above cell. This will open a browser window where you can log in and authorize your marimo notebook to access your MotherDuck database. In order to avoid being prompted each time you open a notebook, you can set the motherduck_token environment variable:
export motherduck_token="your_token"
marimo edit
Once connected, your MotherDuck tables are automatically discovered in the Datasources Panel:
2. Writing SQL Queries
You can query your MotherDuck tables using SQL cells in marimo. Here's an example of how to query a table and display the results using marimo:
marimo's reactive execution model extends into SQL queries, so changes to your SQL will automatically trigger downstream computations for dependent cells (or optionally mark cells as stale for expensive computations).
3. Mixing SQL and Python
MotherDuck allows you to seamlessly mix SQL queries with Python code, enabling powerful data manipulation and analysis. Here's an example:
This example demonstrates how you can use SQL to query your data, then use Python and marimo to further analyze and visualize the results.
Example Notebook
For a full example of using MotherDuck with marimo, check out our MotherDuck example notebook.
marimo edit https://github.com/marimo-team/marimo/blob/main/examples/sql/connect_to_motherduck.py