Skip to content

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.

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_status becomes deleted, its audit log records instance.expired (actor provisioner/expiry), and the events instance.deleted.v1 and instance.expired.v1 reach your webhooks and the live event stream like other instance events.

A TTL on a branch deletes only that branch, never its parent.

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.

RuleDetail
Range3600 to 2592000 seconds (1 hour to 30 days); anything else is refused with 422
DeadlineThe TTL counts from the request: setting ttl_seconds: 86400 today means “delete 24 hours from now”
Setting a first TTL or an earlier deadlineSchedules 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 TTLinstances:operate on the project
Deletion protectionA 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 deadlineThe 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 organizationsEvery lookup is scoped to the organization in the URL; another organization’s instance is a 404
ImpersonationSupport 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).

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.

Terminal
zb instances create --engine postgres --ttl 24h # a transient database, deleted in 24 hours
zb branch create inst_01main --name ci-1234 --ttl 2h # a transient branch
zb instances get inst_01scratch # shows "expires: ..." for a transient instance
zb instances extend inst_01scratch --ttl 7d # delete it 7 days from now instead
zb 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.

CallNeeds
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}/ttlinstances: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.

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.