# Experiments

An experiment tests a change on a throwaway clone of your database, and leaves the database itself alone.
The clone is version-matched to the original and built from a topology snapshot.
DBGorilla measures the change on the clone and reports the result.

## Turn it on

There is nothing to turn on, and there is no Experiments page to open.
An agent runs experiments while it investigates a problem in your database.
An assistant connected over MCP can run one when you ask it about a proposed change.

The results appear in the investigation's report.
For example, a report on a missing index measured foreign-key checking on a clone with about
310,000 orders: 15.104 ms per customer deleted without the index, and 0.108 ms with it.

## Choose what goes in the clone

You can build the clone in three ways.
Each mode answers a different question:

| Mode | What is in the clone | Good for |
|---|---|---|
| Planner replay | No data, your production statistics restored | Plans, costs, index what-ifs |
| Synthetic execution | Generated rows at realistic volume | Real timings and I/O |
| Hybrid | Generated rows plus production statistics | A production plan running over synthetic data |

Planner replay is the quickest and answers most questions, because a plan change is usually what
you need to evaluate.
Use synthetic execution when you need a measured runtime rather than a cost estimate.
Its results are real timings on synthetic data.

The generated rows are invented rather than copied.
A clone of a table whose rows hold names like `c1` and `c2` was filled with text such as
`repudiandae fuga sunt.`, and none of its rows matched the production pattern.

The clone carries your schema, including views, indexes, constraints and the extensions your
database uses.
It does not carry your roles: the clone's only non-system role was `postgres`.

## Know what an experiment can reach

The experiment runs in an isolated environment that can reach the clone and nothing else, then
returns the measurements.
Its code runs in a sandboxed Python with one function for running SQL against the clone.
An attempt to open a network connection from inside it failed, both to a public address and to the
database the clone was built from.

## Use it from your editor

An assistant connected through [Connect your editor](/docs/integrations/editor/) runs an
experiment with `run_experiment`.
It names a snapshot, a member and a database, picks one of the three modes, and supplies a short
Python script that runs SQL against the clone and prints what it finds.

## Related

- [Sandboxes](/docs/using-dbgorilla/sandboxes/): the same clone machinery, while you drive it.
- [Query performance](/docs/using-dbgorilla/query-performance/#test-an-index-before-you-build-it):
  the Hypothetical Index tab, a planner replay experiment with one question already filled in.
- [Connect your editor](/docs/integrations/editor/): use these tools from an AI assistant.