Database tools
Transient databases and branches
Tested with:Databasezy API v1 · zb CLI · ZB-607 (written; live check pending)
A transient database or branch has a time to live (TTL). When the TTL runs out, Databasezy deletes it for you. Use it for scratch databases, CI runs, previews and agent experiments that should not outlive the task. Any instance or branch can have a TTL between 1 hour and 30 days. You can extend it, shorten it or remove it until it expires.
What happens when the TTL expires
Section titled “What happens when the TTL expires”Within a few minutes after the deadline (the sweep runs every minute), the database is deleted the same way as when you delete it yourself:
- Compute stops and billing for it stops at that moment.
- Its data and backups are kept for your plan’s retention window after deletion, then purged. A TTL never erases a database early and never removes a backup that the retention rules keep.
- The instance’s
desired_statusbecomesdeleted, its audit log recordsinstance.expired(actorprovisioner/expiry), and the eventsinstance.deleted.v1andinstance.expired.v1reach your webhooks and the live event stream like other instance events.
A TTL on a branch deletes only that branch, never its parent.
Notices
Section titled “Notices”Your organization’s owners and admins with a verified email address get an email 24 hours and 1 hour before the deadline, once per deadline. A notice is only sent when its window existed when the TTL was set: a database created with a 2-hour TTL gets the 1-hour notice only, and one with a 1-hour TTL gets none. If you extend the TTL, the new deadline gets its own notices. The notices follow your Instances email preference. The instance page in the portal always shows the deadline.
| Rule | Detail |
|---|---|
| Range | 3600 to 2592000 seconds (1 hour to 30 days); anything else is refused with 422 |
| Deadline | The TTL counts from the request: setting ttl_seconds: 86400 today means “delete 24 hours from now” |
| Setting a first TTL or an earlier deadline | Schedules a deletion, so it needs what deleting needs: instances:delete on the project and a second factor completed in the last 15 minutes (403 mfa_required otherwise). API keys need the delete permission and scope |
| Extending or removing a TTL | instances:operate on the project |
| Deletion protection | A database with deletion protection on, and a project’s primary database (the one its Auth, Data API, Storage and Realtime use), refuse a TTL (409). A database with a TTL cannot be chosen as a primary database or be protected |
| After the deadline | The TTL can no longer be changed (409): the database is being deleted, and its data and backups stay for your plan’s retention window |
| Other organizations | Every lookup is scoped to the organization in the URL; another organization’s instance is a 404 |
| Impersonation | Support staff using customer-granted impersonation cannot change a TTL |
Setting a first TTL or an earlier deadline is recorded as a security event (authz.instance_expiry_scheduled).
Every TTL change is written to the audit log (instance.ttl_set, instance.ttl_cleared).
In the portal
Section titled “In the portal”The instance overview shows Expires in its details. A transient database also shows a card with the deadline, a choice of a new deletion time (1 hour, 24 hours, 7 days or 30 days from now), Extend and Keep permanently. If the change needs a second factor, the card links to the confirmation.
With the zb CLI
Section titled “With the zb CLI”zb instances create --engine postgres --ttl 24h # a transient database, deleted in 24 hourszb branch create inst_01main --name ci-1234 --ttl 2h # a transient branchzb instances get inst_01scratch # shows "expires: ..." for a transient instancezb instances extend inst_01scratch --ttl 7d # delete it 7 days from now insteadzb instances extend inst_01scratch --keep # remove the TTL: keep it until you delete it--ttl takes hours or minutes (90m, 24h) or whole days (7d), from 1 hour to 30 days. The CLI checks the
range before calling the API.
With the API
Section titled “With the API”| Call | Needs |
|---|---|
POST /v1/orgs/{org}/projects/{project}/instances {…, ttl_seconds} | instances:create (201) |
POST /v1/orgs/{org}/instances/{id}/branches {name, …, ttl_seconds} | instances:create on the project (202) |
PUT /v1/orgs/{org}/instances/{id}/ttl {ttl_seconds} | instances:operate to extend; instances:delete and a recent second factor for a first TTL or an earlier deadline (200) |
DELETE /v1/orgs/{org}/instances/{id}/ttl | instances:operate (200) |
Every instance and branch in a response has expires_at: the deadline as an RFC 3339 time, or null for a
permanent one. Use the branch’s own instance id with the ttl routes to change a branch’s TTL.
With MCP
Section titled “With MCP”create_instance and create_branch take ttl_seconds (3600 to 2592000). Agents can create a scratch database
that cleans itself up; extending or removing a TTL is done in the portal, with the CLI or with the API.