> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app to MotherDuck

> Connect your app to MotherDuck, the cloud service for DuckDB, to query your data with SQL and build dashboards and reports in your Lovable app.

export const connector_0 = "MotherDuck"

[MotherDuck](https://motherduck.com/) is the cloud service for DuckDB, an analytical SQL database. It hosts your DuckDB databases and shares, and runs DuckDB SQL over them. A share is a read-only copy of a database that another MotherDuck user shares with you. You can load data into MotherDuck from files such as Parquet, CSV, and JSON. The MotherDuck connector lets your Lovable app run read-only SQL against those databases, browse their tables and columns, and turn the results into dashboards, reports, and data tools. It's designed for apps that sit on top of data you already keep in MotherDuck.

MotherDuck is available as an [app + chat connector](/integrations/app-connectors): one shared connection that works in the project chat while you build and in your published apps.

With MotherDuck, your app can:

* Run DuckDB SQL queries against your MotherDuck databases and attached shares
* List databases, tables, views, and columns so Lovable builds against real schema names
* Search your catalog for tables and columns by keyword
* Build dashboards and reports that aggregate data in SQL
* Insert or update rows when you explicitly ask for it and your token allows writes

Lovable runs queries in MotherDuck's read-only mode unless you ask it to change data. MotherDuck blocks changes to your data in that mode.

In the project chat, Lovable asks for your approval before it runs a SQL query, including a read-only query. It does not ask before it lists databases, tables, or columns. Your **Agent approval for this connection** setting applies to you and that connection and controls whether Lovable keeps asking. See [Approving connector actions in the project chat](/integrations/app-connectors#approving-connector-actions-in-the-project-chat). A published app does not ask for approval, so Lovable puts features that change data behind your app's sign-in.

## Common use cases and example apps

These examples show what you can build with MotherDuck, each with a prompt to start from.

| Example app | Example prompt | Description |
| :- | :- | :- |
| **Revenue dashboard** | *Use MotherDuck and build a dashboard of monthly revenue and order counts from our orders table.* | **See revenue trends without exporting a CSV.**<br />The app aggregates the orders table in SQL and renders the monthly series as charts. |
| **Table browser** | *Use MotherDuck and build a page that lists the tables in my database and previews the first rows of each.* | **Explore a database without opening a SQL client.**<br />The app lists databases, tables, and columns, then runs a bounded preview query for the table you pick. |
| **Customer 360 view** | *Use MotherDuck and build a customer lookup that shows a customer's orders, spend, and last activity.* | **Bring one customer's history into a single screen.**<br />The app runs a filtered query per customer and shows the results in cards and a table. |
| **Parquet lake explorer** | *Use MotherDuck and build an explorer over the Parquet files we load into MotherDuck, with filters by date and region.* | **Query lake files like tables.**<br />The app runs DuckDB SQL over the loaded data and applies the filters as query predicates. |
| **Data quality monitor** | *Use MotherDuck and build an internal tool that runs our null-rate and duplicate checks nightly and flags failures.* | **Catch bad data before your team does.**<br />The app runs validation queries on a schedule, stores the results, and highlights checks that fail. |
| **Shared dataset viewer** | *Use MotherDuck and build a read-only viewer over the sample\_data share with a search box.* | **Publish a slice of a shared database.**<br />The app queries an attached share and returns matching rows for the search term. |

## How to connect MotherDuck

Who can create MotherDuck connections depends on your plan and workspace settings. App + chat connectors are available by default on Free, Pro, and Business plans. On Enterprise plans, they are effectively disabled at first: [Who can create connections and clients](/integrations/admin-controls#who-can-create-connections-and-clients) defaults to **No one** until an admin changes it in **Connectors → Admin settings → App + chat connectors**.

You can create multiple MotherDuck connections using different access tokens, which is useful for separating environments (for example, a Read Scaling token for a published dashboard and a Read/Write token for an admin tool).

When the connection is created, you can [link it to the projects](/integrations/app-connectors#link-a-connection-to-a-project) where you want to use it. Anyone building in a project can ask Lovable in the project chat to link their project to it.

### Prerequisites

Before connecting MotherDuck, make sure you have:

* A MotherDuck account with at least one database or attached share
* A MotherDuck access token
* Permission to **create connections** in your Lovable workspace (see [Who can create connections and clients](/integrations/admin-controls#who-can-create-connections-and-clients))

<Note>
  All queries through this connector run on your MotherDuck account and count toward your MotherDuck plan and compute usage. Billing is handled directly by MotherDuck, not Lovable.
</Note>

### Step 1: Get a MotherDuck access token

A MotherDuck access token lets your Lovable app authenticate with MotherDuck. MotherDuck offers two token types, and the type decides what the connection can do:

* A **Read/Write** token can read and, when you explicitly ask for it, change data and schema.
* A **Read Scaling** token connects to read replicas that reject every write. Choose it for dashboards and other read-only apps. Data from a Read Scaling token can be a few minutes behind the latest changes. The token can query only the databases and shares that you attached with a Read/Write token first.

To create a MotherDuck access token:

<Steps>
  <Step title="Open your MotherDuck account">
    Sign in to [MotherDuck](https://app.motherduck.com/).
  </Step>

  <Step title="Open Access Tokens">
    Click your organization name, then **Settings**, and open **Access Tokens**.
  </Step>

  <Step title="Create a token">
    Click **Create token**. Give it a descriptive name, for example `Lovable integration`, choose **Read/Write** or **Read Scaling**, and decide whether the token expires.
  </Step>

  <Step title="Copy the token">
    Copy the token and store it securely. MotherDuck shows it only once.
  </Step>
</Steps>

<Warning>
  Your access token functions like a password. Keep it secure and never share it publicly. You'll need it in the next step.
</Warning>

See MotherDuck documentation for more: [Authenticating to MotherDuck](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/) and [Read scaling](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/).

### Step 2: Connect MotherDuck to Lovable

Open the connection form and enter the token from Step 1.

<Steps>
  <Step title="Open MotherDuck in Connectors">
    Open [**Connectors**](https://lovable.dev/dashboard?connectors) and select **MotherDuck**. For the other places to open the catalog from, see [Where to find connectors](/integrations/introduction#where-to-find-connectors).
  </Step>

  <Step title="Add a connection">
    Click **Add connection** and select **App + chat connector**. The form is split into collapsible sections, **Details**, **Configure connection**, and **Sharing**.
  </Step>

  <Step title="Name the connection">
    Under **Details**, Lovable fills in a name for the connection, which you can change. The name is only used inside Lovable to identify the connection.
  </Step>

  <Step title="Configure the connection">
    Under **Configure connection**, enter:

    1. **MotherDuck access token**: paste the token you copied. **Get value** next to the field opens MotherDuck's token documentation.
  </Step>

  <Step title="Choose who can use this connection">
    Under **Sharing**, the connection is private to you by default and shows a **Private** label. To share it, click **Share with others**. Then add workspace members by email, or click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

    Everyone you add can query all the databases and shares that the token's MotherDuck user can read.

    See [Who can use connections and clients](/integrations/admin-controls#who-can-use-connections-and-clients) for more information.
  </Step>

  <Step title="Connect">
    Click **Connect**. Lovable verifies the token against MotherDuck by listing your databases before saving the connection.
  </Step>
</Steps>

When connected, anyone building in a project can ask Lovable in the project chat to link their project to MotherDuck (based on configured connection-level access). Your Lovable apps can then query your MotherDuck databases and shares through the connection.

## Working with query results

MotherDuck returns at most 2,048 rows or 50,000 characters per query and stops a query after 55 seconds. Lovable adds a row limit to the queries it writes and aggregates in SQL where it can. When you ask for a page that shows many rows, ask Lovable to paginate or filter rather than load a whole table.

Each query uses MotherDuck compute. If your app reads the same data on a schedule or on every page view, tell Lovable how fresh the data must be. Lovable can then cache the results for that time.

## Limitations

The MotherDuck connector cannot:

* Query a DuckDB database file on your computer or your own server. Only databases and shares hosted in MotherDuck are reachable. Load the file into MotherDuck first.
* Write to a share attached from another account. Shares are read-only.
* Support per-end-user MotherDuck login. Each connection represents a single MotherDuck account shared across all projects linked to it.

To replace the token, for example after it expires or after you revoke it in MotherDuck, create a new token, open the connection in Lovable, and click **Update** under **Configure connection**.

## Manage your {connector_0} connection

Connections are managed from [**Connectors**](https://lovable.dev/dashboard?connectors): select **{connector_0}**, then open the connection.

* **Unlink projects** to remove {connector_0} access from specific projects while keeping the connection available for others. See [Unlink projects from a connection](/integrations/app-connectors#unlink-projects-from-a-connection) for the steps.
* **Delete the connection** to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use {connector_0} stop working until a new connection is added. See [Delete a connection](/integrations/app-connectors#delete-a-connection) for the steps and who can delete.


## Related topics

- [Generate files and analyze data](/features/generate-files.md)
- [Connect your app to Workday](/integrations/workday.md)
- [Connect your app to Notion](/integrations/notion.md)
- [Connect your app to Neon](/integrations/neon.md)
- [Connect your app to Granola](/integrations/granola.md)