# Sandboxes and clones

A sandbox is a real database that DBGorilla runs for you, built from your component's schema or
from schema you paste in.
Use a sandbox for changes you would not try in production: a migration, an index, a rewrite, or
a `DROP`.

The product calls these **Sandbox Deployments**.
Open a component and choose **Sandbox** in its sidebar.
The **Sandboxes** page at the top level of the app lists every sandbox in your account.

## Turn it on

There is nothing to turn on.
A sandbox built from a component needs at least one topology snapshot of it, which the collector
takes on its own.

## Create a sandbox

**From a component.** On the component's Sandbox page, **Create deployment** opens a form in four
steps:

1. **Snapshot.** Pick the topology snapshot to build from.  The newest is selected.
2. **Databases.** Pick which of the component's databases to clone.  All of them are selected, and
   each becomes a database in the sandbox.
3. **Mock data.** Leave it off for a schema-only sandbox, or turn on **Populate with mock data**
   and add tables with a row count for each.
4. **Review.** Name the sandbox and create it.

Engine and version follow the parent.

When you add mock data, select only the database that holds those tables.
A sandbox with two databases selected and mock data for `public.customers` failed with
`relation "public.customers" does not exist`, because that table existed in only one of them.

**From pasted DDL.** **Create deployment** on the top-level Sandboxes page creates a sandbox with no
component or snapshot.
Pick the engine and version, and paste schema into the form.
Leave the schema empty to get an empty database with the engine and version you selected.

DBGorilla provisions a sandbox in the background.
The list updates each row's status during provisioning.

### Statuses

| Status | Meaning |
|---|---|
| `provisioning` | DBGorilla is creating and seeding it.  Only the Details tab opens. |
| `active` | Ready. |
| `failed` | The seed stopped partway.  The row carries the error message. |
| `terminating` | DBGorilla is deleting it. |

A sandbox usually fails because the seed hit something the clone does not have.
The message on the row comes from the seeder rather than a generic handler, so read it before
trying again.

## Know what a sandbox contains

A sandbox built from a snapshot gets your schema and none of your data.
The seed applies the schema and then either leaves the tables empty or fills them with generated
rows you requested.

| Copied | Not copied |
|---|---|
| Schema: tables, columns, indexes, constraints, views | Your table data |
| The engine and major version of the parent | Your users, roles and grants |
| The extensions your schema uses | |

The clone records which snapshot it came from and when, and which databases it was forked from.
A sandbox created last Tuesday keeps that snapshot.

### Extensions

The sandbox image includes `vector` (pgvector), `hypopg`, `pg_stat_kcache`, `pg_qualstats`,
`pg_wait_sampling`, `pg_cron`, `postgis` and `plpgsql_check`.
Run `CREATE EXTENSION` for the ones you need.
`pg_stat_statements` is preloaded.

## Work in a sandbox

Open a sandbox to see five tabs.

**Details** shows the sandbox's status, engine and version, the snapshot it was forked from, and
when it was created.

**Browse** is the table browser for the clone.

**Schema** draws the clone's tables, columns and constraints.

**SQL Executor** is the editor for the clone.
Statements you run there can write rows, alter a table, or drop one.

Browse, Schema and SQL Executor share a **Database** picker.
A sandbox can hold several databases, and a schema name from one has no meaning in another.

**Connection** says that direct connections to sandbox databases are not available yet.

## Generate data

You can request rows instead of an empty schema.
In the form you add tables and a row count for each, and the rows are generated consistent with
the foreign keys between them.
Through the API, a table can instead take a fanout: a minimum and maximum number of child rows for
each row of a parent table.

The generator is sized for testing shapes and plans:

- up to 50,000 rows per table
- up to 500 tables
- up to 1,000 children per parent row in a fanout

The form stops a row count at 50,000.
Past a limit, the API refuses the request and names the limit, and the table when one table is
over:
`population.tables['public.c'].records may be at most 50000 for a sandbox (got 50001)`.

## Leave it idle

A sandbox **hibernates five minutes after its last connection drops**.
While it is asleep, its database server is stopped.
Opening it in DBGorilla wakes it up, which took about a minute and a half for a small sandbox.
You do not need to stop it after you finish for the day.

A sandbox stays until you delete it.
It stays in the list even after the component it was forked from is deleted.
Delete sandboxes you no longer need.

Without an account you can create one sandbox.
A second attempt shows this message:
"You have used all the sandboxes in this guest session. Create an account to build more".
A signed-in account is not held to one.

## Delete a sandbox

Delete a sandbox from the list with **Delete deployment**, then confirm.
The clone and everything in it are deleted: the database, its schema, and anything you wrote into
it.
Its row leaves the list.

What deletion does not touch is the snapshot it was forked from.
That snapshot belongs to the parent component.
A new sandbox from the same snapshot has the same starting point.

## Other features that use a clone

You do not always create a clone deliberately.

**Hypothetical Index** on the
[Query performance](/docs/using-dbgorilla/query-performance/#test-an-index-before-you-build-it) page
tests a candidate index against the planner on a clone.
It injects your production statistics so the result reflects your data distribution.
Its clone does not appear in the Sandboxes list.

**[Experiments](/docs/using-dbgorilla/experiments/)** run by an agent use a clone for the same
reason.
They produce a result without modifying the database they examine.

## Use it from your editor

An assistant connected through [Connect your editor](/docs/integrations/editor/) does not create
sandboxes.
It runs experiments instead, on a clone built for that one run.

## Related

- [Experiments](/docs/using-dbgorilla/experiments/): what an agent measures on a clone.
- [Query performance](/docs/using-dbgorilla/query-performance/): test an index before you build it.
- [Connect your editor](/docs/integrations/editor/): use DBGorilla from an AI assistant.