feat: support HTTP DuckDB queries in WASM notebooks (#9480)

Motivated by marimo-team/quarto-marimo#74,
marimo-team/jupyter-book-marimo#1, and #9413.

DuckDB remote file queries fail in Pyodide because DuckDB-WASM [can't
use httpfs](https://duckdb.org/2024/10/02/pyodide#limitations).
Therefore, URL-based SQL like `FROM
'https://...'` and `read_csv/read_parquet/read_json('https://...')` are
unusable in WASM notebooks today.

This PR adds a DuckDB WASM fallback layer for `mo.sql`, SQL cells, raw
`duckdb.sql/query/execute/query_df`, connection SQL methods, and direct
`duckdb.read_csv/read_parquet/read_json` calls.

It translates queries such as

```sql
SELECT * FROM read_csv('https://example.com/cars.csv')
SELECT * FROM 'https://example.com/cars.csv'
-- or duckdb.read_csv('https://example.com/cars.csv') via Python API
```

into

```sql
SELECT * FROM __marimo_wasm_duckdb_remote_0
```

where `__marimo_wasm_duckdb_remote_0` is bound to a fetched pandas
DataFrame, which DuckDB can query through Python replacement scans.

Underneath, the fallback layer:

- uses sqlglot to analyze SQL and extract supported static remote file
references from the AST
- fetches remote files through Python/urllib via marimo's shared WASM
fetch util
- decodes fetched DuckDB file bytes into pandas DataFrames
- hands those DataFrames back to DuckDB under generated table names

Unsupported or dynamic cases are left to DuckDB's normal path. The patch
is a no-op outside Pyodide, and in Pyodide the DuckDB SQL fallback
requires `sqlglot` for AST analysis.

Tested with unit coverage for the rewrite/fetch/read paths and manually
in the WASM playground against hosted CSV, parquet, JSON, and GeoJSON
datasets.

## WASM Playground Demo

Demonstrates that the Pyodide-build of marimo supports querying remote
files with DuckDB across cases like:

- CSV via `mo.sql`: direct URL scan
- Parquet via `duckdb.sql`: `read_parquet(...)`
- Direct `duckdb.read_csv` Python API with patched options (custom
delimiter)
- JSON / GeoJSON path
- Connection API via `duckdb.connect`


https://github.com/user-attachments/assets/a2b310ed-2677-4f67-81da-3d8ea2145254

Author: peter-gy

frontend/src/core/islands/worker/worker.tsx

@@ -9,6 +9,7 @@ import {
 } from "rpc-anywhere";
 import type { NotificationPayload } from "@/core/kernel/messages";
 import type { ParentSchema } from "@/core/wasm/rpc";
+import { shouldLoadDuckDBPackages } from "@/core/wasm/utils";
 import { TRANSPORT_ID } from "@/core/wasm/worker/constants";
 import { getPyodideVersion } from "@/core/wasm/worker/getPyodideVersion";
 import { MessageBuffer } from "@/core/wasm/worker/message-buffer";
@@ -85,8 +86,8 @@ const requestHandler = createRPCRequestHandler({
   loadPackages: async (code: string) => {
     await pyodideReadyPromise; // Make sure loading is done
 
-    if (code.includes("mo.sql")) {
-      // Add pandas and duckdb to the code
+    if (shouldLoadDuckDBPackages(code)) {
+      // Add pandas and duckdb to the code for mo.sql and for remote duckdb sources
       code = `import pandas\n${code}`;
       code = `import duckdb\n${code}`;
       code = `import sqlglot\n${code}`;

frontend/src/core/wasm/__tests__/utils.test.ts

@@ -0,0 +1,34 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import { shouldLoadDuckDBPackages } from "../utils";
+
+describe("shouldLoadDuckDBPackages", () => {
+  it("loads for mo.sql", () => {
+    expect(shouldLoadDuckDBPackages('df = mo.sql("SELECT 1")')).toBe(true);
+  });
+
+  it("loads for duckdb imports and usage", () => {
+    expect(shouldLoadDuckDBPackages("import duckdb")).toBe(true);
+    expect(shouldLoadDuckDBPackages("from duckdb import sql")).toBe(true);
+    expect(shouldLoadDuckDBPackages("import pandas, duckdb")).toBe(true);
+    expect(shouldLoadDuckDBPackages("rows = duckdb.sql('SELECT 1')")).toBe(
+      true,
+    );
+  });
+
+  it("loads when package discovery found duckdb", () => {
+    expect(
+      shouldLoadDuckDBPackages("print('hello')", new Set(["duckdb"])),
+    ).toBe(true);
+  });
+
+  it("does not load for incidental duckdb text", () => {
+    expect(shouldLoadDuckDBPackages("name = 'duckdb'")).toBe(false);
+    expect(shouldLoadDuckDBPackages("# import duckdb")).toBe(false);
+  });
+
+  it("does not load without mo.sql, duckdb usage, or discovery", () => {
+    expect(shouldLoadDuckDBPackages("print('hello')")).toBe(false);
+  });
+});

frontend/src/core/wasm/utils.ts

@@ -10,3 +10,17 @@ export function isWasm(): boolean {
     document.querySelector("marimo-wasm") !== null
   );
 }
+
+const DUCKDB_USAGE_PATTERN =
+  /(^|\n)\s*(?:import\s+[^\n#]*\bduckdb\b|from\s+duckdb\b|[^\n#]*\bduckdb\s*\.)/;
+
+export function shouldLoadDuckDBPackages(
+  code: string,
+  foundPackages?: ReadonlySet<string>,
+): boolean {
+  return (
+    code.includes("mo.sql") ||
+    DUCKDB_USAGE_PATTERN.test(code) ||
+    foundPackages?.has("duckdb") === true
+  );
+}

frontend/src/core/wasm/worker/bootstrap.ts

@@ -9,6 +9,7 @@ import { WasmFileSystem } from "./fs";
 import { getMarimoWheel } from "./getMarimoWheel";
 import { t } from "./tracer";
 import type { SerializedBridge, WasmController } from "./types";
+import { shouldLoadDuckDBPackages } from "../utils";
 
 const MAKE_SNAPSHOT = false;
 
@@ -163,8 +164,8 @@ export class DefaultWasmController implements WasmController {
   private async loadNotebookDeps(code: string, foundPackages: Set<string>) {
     const pyodide = this.requirePyodide;
 
-    if (code.includes("mo.sql")) {
-      // We need pandas and duckdb for mo.sql
+    if (shouldLoadDuckDBPackages(code, foundPackages)) {
+      // We need pandas and duckdb for mo.sql and for remote duckdb sources
       code = `import pandas\n${code}`;
       code = `import duckdb\n${code}`;
       code = `import sqlglot\n${code}`;

frontend/src/core/wasm/worker/worker.ts

@@ -34,6 +34,7 @@ import type {
   SerializedBridge,
   WasmController,
 } from "./types";
+import { shouldLoadDuckDBPackages } from "../utils";
 
 /**
  * Web worker responsible for running the notebook.
@@ -141,8 +142,8 @@ const requestHandler = createRPCRequestHandler({
     const span = t.startSpan("loadPackages");
     await pyodideReadyPromise; // Make sure loading is done
 
-    if (code.includes("mo.sql")) {
-      // Add pandas and duckdb to the code
+    if (shouldLoadDuckDBPackages(code)) {
+      // Add pandas and duckdb to the code for mo.sql and for remote duckdb sources
       code = `import pandas\n${code}`;
       code = `import duckdb\n${code}`;
       code = `import sqlglot\n${code}`;

marimo/_output/formatters/df_formatters.py

@@ -19,6 +19,7 @@
 from marimo._plugins.stateless.plain_text import plain_text
 from marimo._plugins.ui._impl import tabs
 from marimo._plugins.ui._impl.table import get_default_table_page_size, table
+from marimo._runtime._wasm._duckdb import patch_duckdb_for_wasm
 from marimo._runtime._wasm._polars import patch_polars_for_wasm
 
 LOGGER = _loggers.marimo_logger()
@@ -160,6 +161,17 @@ def _show_marimo_dataframe(
             return table(df, selection=None, pagination=None)._mime_()
 
 
+class DuckDBFormatter(FormatterFactory):
+    """Use DuckDB's lazy import hook to install WASM runtime patches."""
+
+    @staticmethod
+    def package_name() -> str:
+        return "duckdb"
+
+    def register(self) -> Unregister:
+        return patch_duckdb_for_wasm()
+
+
 class DataFusionFormatter(FormatterFactory):
     @staticmethod
     def package_name() -> str:

marimo/_output/formatters/formatters.py

@@ -18,6 +18,7 @@
 from marimo._output.formatters.cell import CellFormatter
 from marimo._output.formatters.df_formatters import (
     DataFusionFormatter,
+    DuckDBFormatter,
     IbisFormatter,
     PolarsFormatter,
     PyArrowFormatter,
@@ -54,6 +55,7 @@
     AltairFormatter.package_name(): AltairFormatter(),
     MatplotlibFormatter.package_name(): MatplotlibFormatter(),
     DataFusionFormatter.package_name(): DataFusionFormatter(),
+    DuckDBFormatter.package_name(): DuckDBFormatter(),
     IbisFormatter.package_name(): IbisFormatter(),
     PandasFormatter.package_name(): PandasFormatter(),
     PolarsFormatter.package_name(): PolarsFormatter(),