# 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)


---

## 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/dev-tools/shadowtraffic/",
  "page_title": "ShadowTraffic",
  "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.