Skip to content

Database tools

Deletion protection

Tested with:Databasezy API v1 · zb CLI · ZB-711 (written; live check pending)

Deletion protection is a per-database switch, like deletion protection on Amazon RDS or Cloud SQL. While it is on, Databasezy refuses every action that would delete the database or replace its data in place. Turn it on for production databases so that a script, a mistyped command or an agent cannot remove them by accident.

It is off by default. You turn it on when you create a database or at any time afterwards.

While deletion protection is on, these requests are refused with 409 Conflict and a message that names the database and says how to turn protection off:

ActionWhere
Delete the database (or a branch that has it on)DELETE /v1/orgs/{org}/instances/{id}, branch delete, portal, zb instances delete, MCP delete_instance
Erase the databasePOST /v1/orgs/{org}/instances/{id}/actions/erase
Give it a TTL (a scheduled deletion)PUT /v1/orgs/{org}/instances/{id}/ttl, zb instances extend --ttl
Reset a branch that has it onPOST .../branches/{branch}/reset
Promote a branch into itPOST .../branches/{branch}/promote
Restore a backup in placePOST .../backups/{backup}/actions/restore with mode: in_place
Run a migration that drops its objects firstPOST .../migrations with options.drop_target: true

The refusal comes before the second-factor check, so you are not asked for a code for something that will be refused anyway. Every refusal is recorded as a security event (authz.deletion_protection_refused).

These still work while it is on: reading and writing data, pausing and resuming, resizing and other settings changes, backups, restoring a backup into a new database, creating branches from it, and migrations that only add data.

ChangeNeeds
Turn it onWrite access to instances (instances:operate on the project: Developer, Admin, Owner or a team operator role). Refused (409) while the database has a TTL: remove the TTL first
Turn it offWhat deleting needs: instances:delete on the project (Admin or Owner) and a second factor completed in the last 15 minutes (403 mfa_required otherwise). API keys need the delete permission and the instances:delete scope

Both changes are written to the audit log (instance.deletion_protection_enabled, instance.deletion_protection_disabled) and sent as the event instance.deletion_protection_changed.v1 to your webhooks and the live event stream. Turning it off is also recorded as a security event (authz.instance_deletion_protection_disabled). Support staff using customer-granted impersonation cannot change it.

A database with deletion protection cannot have a TTL, and a database with a TTL cannot be protected: a protected database is never deleted automatically.

Deletion protection guards against accidents, not against closing your account. When the organization owner closes the organization (which needs the owner’s own second factor and the organization’s slug typed), every database is deleted, protected or not; the audit row of the closure lists the protected ones. Data and backups are then kept for your plan’s retention window, as for any deleted database.

Deletion protection is opt-in, for every plan. Databasezy does not turn it on for you: CI pipelines, previews and scratch databases are created and deleted by automation all the time, and a default that silently blocked those deletes would break them. We recommend turning it on for every production database, and creating production databases with it from the start (--deletion-protection in the CLI, deletion_protection: true in the API).

Instance → Settings → Deletion protection has the switch and says why it cannot be used when you lack the permission or the database has a TTL. Turning it off asks you to confirm. While it is on, the Delete and Erase buttons are disabled with a note. The instance overview shows Deletion protection: On / Off in its details.

Terminal
zb instances create --engine postgres --name orders --deletion-protection # create it protected
zb instances get inst_01orders # shows "deletion protection: on"
zb instances update inst_01orders --deletion-protection # turn it on later
zb instances update inst_01orders --deletion-protection=false # turn it off (asks to confirm)

--deletion-protection cannot be combined with --ttl. Turning it off with a user session needs a recent second factor; the CLI prints the API’s mfa_required answer when one is needed.

CallNeeds
POST /v1/orgs/{org}/projects/{project}/instances {…, deletion_protection: true}instances:create (201); with ttl_seconds too it is refused (422, field deletion_protection)
PUT /v1/orgs/{org}/instances/{id}/deletion-protection {enabled: true}instances:operate (200)
PUT /v1/orgs/{org}/instances/{id}/deletion-protection {enabled: false}instances:delete and a recent second factor (200)

Every instance and branch in a response has deletion_protection (true or false). Asking for the value the database already has is answered 200 and changes nothing. Every lookup is scoped to the organization in the URL; another organization’s database is a 404.

get_instance returns deletion_protection. MCP cannot change it: an agent that gets a 409 from delete_instance should tell you, and you decide whether to turn protection off.

A deletion_protection attribute in the Terraform provider and the SDKs is planned; until then use the API, the CLI or the portal.