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
Section titled “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
Section titled “Create a sandbox”From a component. On the component’s Sandbox page, Create deployment opens a form in four steps:
- Snapshot. Pick the topology snapshot to build from. The newest is selected.
- Databases. Pick which of the component’s databases to clone. All of them are selected, and each becomes a database in the sandbox.
- 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.
- 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Other features that use a clone”You do not always create a clone deliberately.
Hypothetical Index on the Query performance 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 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
Section titled “Use it from your editor”An assistant connected through Connect your editor does not create sandboxes. It runs experiments instead, on a clone built for that one run.
Related
Section titled “Related”- Experiments: what an agent measures on a clone.
- Query performance: test an index before you build it.
- Connect your editor: use DBGorilla from an AI assistant.