# MotherDuck Documentation - Dev Tools > Developer tools and utilities that work with MotherDuck Generated: 2026-08-25 > MotherDuck is a serverless cloud data warehouse built on DuckDB. It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics. ## Key capabilities - **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses) - **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session - **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language - **Data Sharing**: Share databases and query results with team members and external users - **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI - **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more - **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation ## When to use MotherDuck Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. ## Agent guidance If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation. For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows. To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question. For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json. ## Account setup for agents If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request. `POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`. Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership. Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup. ## Included documentation Source: https://motherduck.com/docs/integrations/dev-tools/retool # Retool > Low-code platform for building internal tools and custom business applications with drag-and-drop UI components. There are two ways to connect Retool to MotherDuck, depending on whether you use Retool Cloud or self-hosted Retool. ## Retool Cloud (native connector) Retool Cloud has a native MotherDuck resource type. To connect: 1. Go to **Resources** and select **Create new** > **Resource**. 2. Search for **MotherDuck** and select it. 3. Give the resource a descriptive name (for example, "MotherDuck analytics"). 4. Under **Resource credentials**, enter your [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token). 5. Optionally enter a **Database name**. Leave it empty to use workspace mode, which lets you query across multiple databases. 6. Click **Test connection**, then **Create resource**. You can use this resource in your Retool apps to run SQL queries against your MotherDuck databases. The resource supports both SQL mode for reading data and GUI mode for write operations (insert, update, delete, upsert). ### Connection options You can pass optional key-value pairs under **Connection options** to customize behavior: | Option | Values | Description | |--------|--------|-------------| | `access_mode` | `READ_WRITE`, `READ_ONLY` | Controls whether the connection can write data | | `attach_mode` | `single`, `workspace` | Sets the [attach mode](/key-tasks/authenticating-and-connecting-to-motherduck/attach-modes/). `single` scopes the connection to one database (useful when querying a specific tenant or to avoid catalog clutter); `workspace` (default) attaches every database in your saved workspace. | | `TimeZone` | For example, `UTC`, `America/New_York` | Sets the session time zone | | `default_null_order` | `NULLS_FIRST`, `NULLS_LAST` | Default null ordering for queries | | `default_order` | `ASC`, `DESC` | Default sort order for queries | For more details, see the [Retool MotherDuck documentation](https://docs.retool.com/data-sources/guides/connect/motherduck). ### Known limitations - `BLOB` and `ARRAY` column types are not supported by the native connector. Queries that return these types will fail. Cast these columns to a supported type (for example, using `CAST` or `list_string_agg`) or exclude them from your result set. ## Self-hosted (JDBC) If you run a self-hosted Retool instance, you can connect to MotherDuck through the [DuckDB JDBC driver](/integrations/language-apis-and-drivers/jdbc-driver/). Your instance needs network access to `motherduck.com` over HTTPS (port 443). 1. In your Retool instance, go to **Resources** and select **Create new**. 2. Choose **JDBC** as the resource type. 3. Use the following JDBC connection string: ```text jdbc:duckdb:md:?motherduck_token= ``` Replace `` with your MotherDuck database and `` with your [access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token). 4. Test the connection and save. For more details on the JDBC driver, see [JDBC driver](/integrations/language-apis-and-drivers/jdbc-driver/). --- Source: https://motherduck.com/docs/integrations/dev-tools/obsidian # Obsidian > Use the DuckDB & MotherDuck Obsidian plugin to query external data from your notes and freeze the results as markdown tables. The [DuckDB & MotherDuck plugin](https://community.obsidian.md/plugins/duckdb-motherduck) lets you run DuckDB SQL from inside an Obsidian note and freeze the results as a markdown table directly below the query. Local queries run in WASM with no account required. Add a MotherDuck token to query cloud databases or push heavier compute off your laptop. Both backends can coexist in the same note — each code block picks its connection through the fence type. ![MotherDuck SQL block in Obsidian with the rendered result table and the frozen markdown table written below the query](./img/obsidian-motherduck-demo.png) ## Install 1. In Obsidian, open **Settings → Community plugins → Browse**. 2. Search for **DuckDB & MotherDuck** and select **Install**, then **Enable**. To use the cloud backend, add a [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token) under **Settings → DuckDB & MotherDuck → MotherDuck token**. For shared vaults or scoped access, prefer a [service account token](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/). :::warning The MotherDuck token is stored in plaintext in `/.obsidian/plugins/duckdb-motherduck/data.json`. Don't commit or publicly sync a vault that contains it. ::: ## Running queries Each fenced code block picks its backend from the fence language: | Fence | Backend | Reaches cloud | |-------|---------|---------------| | ` ```duckdb ` | Local DuckDB WASM | No | | ` ```motherduck ` | MotherDuck WASM client | Yes | ### Local DuckDB Use a `duckdb` block to query any file format DuckDB reads — Parquet, CSV, JSON, Excel, Iceberg, Delta, or geospatial — from a local path or URL: ````markdown ```duckdb SELECT o_orderpriority AS priority, count(*) AS orders, round(sum(o_totalprice), 2) AS revenue FROM read_parquet('https://shell.duckdb.org/data/tpch/0_01/parquet/orders.parquet') GROUP BY 1 ORDER BY revenue DESC ``` ```` In reading mode the block becomes a panel with **Run**, **Freeze**, and **Clear freeze** buttons. The **Path to local DuckDB file** setting has three modes: - `:memory:` (default) — ephemeral, reset each time Obsidian restarts. - A bare filename like `notes.duckdb` — persistent storage in the browser's Origin Private File System. Survives restart, lives outside your vault. - An absolute path like `/Users/you/data.duckdb` — read an existing `.duckdb` file from disk. Read-only: writes succeed in the worker but don't persist back to the file. ### MotherDuck Use a `motherduck` block to query your cloud databases: ````markdown ```motherduck SELECT type, count(*) AS items, round(avg(score), 1) AS avg_score, round(avg(descendants), 1) AS avg_comments FROM sample_data.hn.hacker_news WHERE type IS NOT NULL GROUP BY 1 ORDER BY items DESC ``` ```` Any DuckDB SQL that runs in MotherDuck works here — joins across databases, AI functions, shared datasets, and so on. ## Freezing results Selecting **Freeze** inserts the query result as a markdown table directly under the SQL block, wrapped in sentinel comments so the next refresh knows what to replace: ````markdown ```motherduck SELECT brand, sum(revenue) FROM sales GROUP BY 1 ORDER BY 2 DESC LIMIT 10 ``` | brand | sum(revenue) | | ----- | ------------ | | acme | 42000 | ```` Frozen tables are regular markdown — they diff cleanly in git, render in any editor, and stay readable to agents that scan the vault. ## Scheduled refresh Pick a cadence in the **Refresh** dropdown above any SQL block to opt that note into auto-refresh. The plugin adds a frontmatter property: ```yaml --- duckdb-motherduck-refresh: daily --- ``` While Obsidian is running, the plugin sweeps once an hour and re-materializes the frozen tables for any note whose cadence has elapsed. The active editor is skipped to avoid stomping in-progress edits. Scheduled refresh runs only while Obsidian is open. To refresh while it's closed, trigger the plugin's API from the [Obsidian CLI](https://obsidian.md/help/cli): ```bash obsidian eval code="app.plugins.getPlugin('duckdb-motherduck').api.refreshFile('path/to/note.md')" ``` Drop that into a cron job, a Claude Code skill, or any agent with shell access. ## Commands From the command palette: - **Refresh all queries in this note** — re-runs every block in the current note. - **Refresh query at cursor** — re-runs and re-freezes only the block at the cursor. Bind a hotkey under **Settings → Hotkeys** for fast iteration. - **Clear freeze at cursor** — removes the frozen result below the SQL block. - **Reset DuckDB / MotherDuck connections** — drops both connections. Use after changing the path or token. ## Settings - **Row cap** — maximum rows rendered inline or written into a frozen table. The runtime stops scanning at `rowCap + 1` rows so heavy queries don't materialize unnecessary data in WASM heap. - **Cell character cap** — maximum characters per cell in rendered and frozen tables. Default `80`. Longer values are truncated with an ellipsis; hover a truncated cell in the live result to see the full value. - **Auto-refresh scheduled notes** — global toggle for the hourly sweep. - **Reset connections after each scheduled refresh** — terminates the WASM workers after each sweep to free memory. Default on. ## Known limitations - Pointing at an on-disk `.duckdb` file is read-only — writes don't persist back to the file. - Scheduled refresh runs only while Obsidian is open; use the plugin API plus the Obsidian CLI for external scheduling. - The MotherDuck token is stored in plaintext in `data.json`. There's no keychain integration. - Absolute-path mode requires Node integration that isn't available on mobile. ## Source The plugin is open source under the MIT license at [motherduckdb/obsidian-duckdb-motherduck](https://github.com/motherduckdb/obsidian-duckdb-motherduck). --- Source: https://motherduck.com/docs/integrations/dev-tools/index # Development Tools > Developer tools and utilities that work with MotherDuck Use MotherDuck with various development tools and utilities to enhance your workflow. ## Included pages - [Retool](https://motherduck.com/docs/integrations/dev-tools/retool): Low-code platform for building internal tools and custom business applications with drag-and-drop UI components. - [Obsidian](https://motherduck.com/docs/integrations/dev-tools/obsidian): Use the DuckDB & MotherDuck Obsidian plugin to query external data from your notes and freeze the results as markdown tables. - [Puppygraph](https://motherduck.com/docs/integrations/dev-tools/puppygraph): Graph visualization tool for exploring and analyzing data relationships in DuckDB. It integrates with MotherDuck for development workflows that read from or write to MotherDuck. - [ShadowTraffic](https://motherduck.com/docs/integrations/dev-tools/shadowtraffic): ShadowTraffic is a synthetic data generation tool for simulating production traffic to your backend. It integrates with MotherDuck for development workflows that read from or write to MotherDuck. - [Vanna](https://motherduck.com/docs/integrations/dev-tools/vanna): Vanna is a data science and AI framework for building and sharing data applications. It integrates with MotherDuck for development workflows that read from or write to MotherDuck. --- Source: https://motherduck.com/docs/integrations/dev-tools/puppygraph # Puppygraph > Graph visualization tool for exploring and analyzing data relationships in DuckDB. It integrates with MotherDuck for development workflows that read from or write to MotherDuck. ## How it works with MotherDuck 1. Create a connection in Puppygraph that targets MotherDuck or DuckDB. 2. Store the MotherDuck token as a secret rather than hard-coding it in project files. 3. Validate the connection with a small query, then build the tool-specific workflow on top of that connection. ## Related content - [View the full process in the Puppygraph documentation](https://docs.puppygraph.com/getting-started/querying-duckdb-data-as-a-graph) - [MotherDuck authentication](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) - [Connecting to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck) --- Source: https://motherduck.com/docs/integrations/dev-tools/shadowtraffic # ShadowTraffic > ShadowTraffic is a synthetic data generation tool for simulating production traffic to your backend. It integrates with MotherDuck for development workflows that read from or write to MotherDuck. ## How it works with MotherDuck ShadowTraffic can generate read and write traffic against a MotherDuck database for development, testing, and load-shaping workflows. ## Prerequisites - ShadowTraffic 1.10.0 or later. - A MotherDuck token. - A target MotherDuck database. ## Setup 1. Create a MotherDuck token and store it in an environment variable such as `MOTHERDUCK_TOKEN`. 2. Add a ShadowTraffic connection with `kind: motherduck`: ```json { "connections": { "md": { "kind": "motherduck", "connectionConfigs": { "token": { "_gen": "env", "var": "MOTHERDUCK_TOKEN" }, "db": "mydb" } } } } ``` 3. Add generators that write to tables or run read queries through that connection. ## Authentication and configuration - Use `token` and `db` for the standard MotherDuck connection. - Use `jdbcUrl` only when you need to control the full JDBC connection string. - Use `queryParams` for MotherDuck connection parameters such as `attach_mode`. - Use `batchConfigs` to tune write batch timing and row count. ## Important notes - ShadowTraffic writes asynchronously. By default it commits when 1000 ms pass or 10000 rows accumulate, whichever happens first. - Automatic table creation is enabled by default. Set `tablePolicy: manual` if you want to manage tables yourself. - For `UPDATE` and `DELETE` operations, generators need a `where` map so ShadowTraffic can identify rows. ## Use cases - Generate synthetic write traffic into MotherDuck tables. - Simulate reads and writes while testing downstream systems. - Use automatic table creation for quick generator iteration, then switch to manual table control for production-like tests. ## Related content - [View the full ShadowTraffic MotherDuck setup guide](https://docs.shadowtraffic.io/connections/motherduck/) - [MotherDuck authentication](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) - [Connecting to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck) --- Source: https://motherduck.com/docs/integrations/dev-tools/vanna # Vanna > Vanna is a data science and AI framework for building and sharing data applications. It integrates with MotherDuck for development workflows that read from or write to MotherDuck. ## How it works with MotherDuck 1. Create a connection in Vanna that targets MotherDuck or DuckDB. 2. Store the MotherDuck token as a secret rather than hard-coding it in project files. 3. Validate the connection with a small query, then build the tool-specific workflow on top of that connection. ## Related content - [View the full process in the Vanna documentation](https://vanna.ai/docs/) - [MotherDuck authentication](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) - [Connecting to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck) --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fintegrations%2Fdev-tools%2F&page_title=MotherDuck%20Documentation%20-%20Dev%20Tools&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.