# SQLMesh
> SQLMesh is a data transformation tool for building and managing data pipelines. It integrates with MotherDuck for running data transformation projects against MotherDuck.
## How it works with MotherDuck

SQLMesh can use MotherDuck as its execution engine for transformation projects.

## Prerequisites

- SQLMesh installed with DuckDB support, for example `sqlmesh[duckdb]`.
- A SQLMesh project.
- A MotherDuck access token. For shared projects, use a service account that owns SQLMesh-managed objects.

## Setup

1. Install SQLMesh with DuckDB support:

   ```bash
   pip install "sqlmesh[duckdb]"
   ```

2. Create a MotherDuck token and store it in `MOTHERDUCK_TOKEN`.
3. Add a MotherDuck gateway to `config.yaml`:

   ```yaml
   gateways:
     motherduck:
       connection:
         type: motherduck
         token: {{ env_var('MOTHERDUCK_TOKEN') }}

   default_gateway: motherduck
   ```

4. Validate the connection:

   ```bash
   sqlmesh info
   ```

5. Run a plan when the connection succeeds:

   ```bash
   sqlmesh plan
   ```

## Authentication and configuration

- Load the token from an environment variable instead of committing it in `config.yaml`.
- SQLMesh supports persistent and ephemeral catalogs for MotherDuck projects.
- The built-in scheduler uses the `motherduck` engine adapter type.

## Important notes

- SQLMesh needs permission to create and access the databases, schemas, and objects it manages.
- Use a service account for shared or automated SQLMesh projects so ownership is stable.
- The SQLMesh documentation also covers advanced connection options such as extensions, connector config, and external-source secrets.

## Use cases

- Run SQLMesh transformation plans against MotherDuck.
- Manage model state and environments with MotherDuck as the execution engine.
- Use service-account credentials for scheduled SQLMesh runs.

## Related content

- [View the full SQLMesh MotherDuck setup guide](https://sqlmesh.readthedocs.io/en/stable/integrations/engines/motherduck/)
- [MotherDuck service accounts](/key-tasks/service-accounts-guide/)
- [Loading data into MotherDuck](/key-tasks/loading-data-into-motherduck/)
- [MotherDuck authentication](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `POST https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

Payload:

```json
{
  "page_path": "/integrations/transformation/sqlmesh/",
  "page_title": "SQLMesh",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed payloads, and `429` when rate-limited.