# DuckDB Analytics with Bonnard

> Connect Bonnard to DuckDB, including MotherDuck, for fast local-first analytics with a YAML semantic layer served to AI agents, dashboards, and your product.

Bonnard turns DuckDB into a governed DuckDB analytics backend with a YAML-defined semantic layer. If you run DuckDB for development, testing, or production workloads (including MotherDuck for cloud-hosted DuckDB), Bonnard connects directly and exposes your metrics through MCP, React SDK, REST API, and markdown dashboards.

## How does Bonnard connect to DuckDB?

Add DuckDB as a datasource in your Bonnard project. Define the connection in your `datasources.yml`:

```yaml
# datasources.yml
datasources:
  - name: duckdb_local
    type: duckdb
    path: ./data/analytics.duckdb

  # Or connect to MotherDuck
  - name: duckdb_cloud
    type: duckdb
    path: md:analytics_db
    token: ${MOTHERDUCK_TOKEN}
```

Then run:

```bash
bon datasource add duckdb_local
bon deploy
```

Bonnard opens your DuckDB database, introspects the schema, and deploys your [semantic layer](/semantic-layer). For MotherDuck, set your token and use the `md:` prefix. Your DuckDB data is queryable through every Bonnard surface within seconds.

## What do you get?

Once connected, your DuckDB data is available through four surfaces:

**[MCP](/glossary/mcp) server.** Run `bon mcp` and your AI agents (Claude, ChatGPT, Cursor) query governed DuckDB metrics with row-level security. Generate publishable keys per tenant for customer-facing [agentic analytics](/agentic-analytics).

**React SDK.** Drop `BarChart`, `LineChart`, and `BigValue` components into your product. Every chart queries your DuckDB database through the semantic layer with multi-tenant access controls applied automatically.

**REST API.** Query metrics programmatically from any language or platform. Type-safe queries with the TypeScript SDK or raw HTTP from anywhere.

**Markdown dashboards.** Author dashboards in markdown, deploy with `bon deploy`, and share governed views with your team or customers.

## How does Bonnard compare to querying DuckDB directly?

| Capability | DuckDB direct | Bonnard + DuckDB |
|------------|--------------|-----------------|
| Metric definitions | SQL scripts, notebooks | YAML semantic layer (version-controlled) |
| AI agent access | None | MCP server with publishable keys |
| Embedded analytics | Build from scratch | React SDK with multi-tenant auth |
| Dashboards | External tools | Markdown dashboards, deployed via CLI |
| Multi-tenancy | Not built-in | Publishable keys + row-level security |
| Pre-aggregation | Manual parquet exports | Automatic pre-aggregation cache |
| Access control | File-level only | YAML-defined RBAC + audit logging |
| Cloud option | MotherDuck | MotherDuck via Bonnard |

## MotherDuck for cloud DuckDB

MotherDuck gives you a cloud-hosted DuckDB with collaboration features. Bonnard connects to MotherDuck the same way it connects to local DuckDB. Use the `md:` path prefix and your MotherDuck token. Your cloud DuckDB becomes a governed analytics backend without changing your existing workflow.

## FAQ

**Does Bonnard support DuckDB?**

Yes. DuckDB is a first-class Bonnard datasource. Both local DuckDB files and MotherDuck cloud databases are supported. Point Bonnard at your `.duckdb` file or MotherDuck connection string and deploy.

**Is DuckDB fast enough for production analytics?**

DuckDB is built for analytical queries and handles millions of rows with sub-second performance on a single machine. Combined with the pre-aggregation cache, repeated queries are cached and served without re-scanning your data.

**Does Bonnard work with MotherDuck?**

Yes. Use the `md:` path prefix and set your `MOTHERDUCK_TOKEN`. Bonnard connects to your MotherDuck database the same way it connects to local DuckDB. All Bonnard features (MCP, React SDK, dashboards, RBAC) work with MotherDuck.

**When should I use DuckDB vs a cloud warehouse?**

DuckDB is ideal for development, prototyping, small-to-medium datasets, and local-first workflows. For petabyte-scale production data, use [Snowflake](/integrations/snowflake), [BigQuery](/integrations/bigquery), or [Databricks](/integrations/databricks). Bonnard works with all of them, so you can start with DuckDB and migrate to a cloud warehouse without changing your [semantic layer](/semantic-layer).

## Related

- [PostgreSQL integration](/integrations/postgres) -- for production application databases
- [What is a Semantic Layer?](/glossary/semantic-layer) -- how metric definitions work
- [How to Connect an AI Agent to Your Data Warehouse](/blog/connect-ai-agent-data-warehouse) -- step-by-step tutorial