Database tools
Branching
Tested with:Databasezy API v1 · zb CLI · ZB-604 (live check: scripts/branch-smoke.py)
A branch is its own database with a copy of another database’s data. Try a migration, a risky query or a new feature on the branch, then reset it to the parent’s current data, promote it back into the parent, or delete it. A branch is a normal instance: it has its own endpoint and its own credentials, it shows up in your database list, and it is billed like any instance (compute per running hour of its size, storage per GB-hour of its volume, and the secure-hosting meter when it is on secure hosting). The Branches page shows each branch’s price per hour.
What a branch copies
Section titled “What a branch copies”| Choice | What the branch gets | Engines |
|---|---|---|
| Full copy (default) | The parent’s schema and rows as they are when the copy runs | Every engine |
| Schema only | Every table, index, view, function and type, no rows; sequences start at their initial values | PostgreSQL |
How the data gets there depends on the cell the parent runs in. On a cell with a volume snapshot driver, a full
branch of PostgreSQL, TimescaleDB or a single-node engine is cut from a snapshot of the parent’s volume
(branch.method: snapshot). Everywhere else, and for every schema-only branch, the branch starts as a new instance
and the platform copies the parent into it with the same instance-to-instance copy as
zb migrate --from another Databasezy instance (branch.method: copy). A copy
branch’s instance reads ready before its copy finishes: branch.data_status in the API says whether it holds its
data yet (copying, masking, ready or failed), the Branches page shows it under the status, and
zb branch create waits for ready (--wait=false returns at once). A copy branch is always placed in its
parent’s cell and tier. The parent must be running while it is copied.
A branch keeps its parent’s placement. A branch of a database on secure hosting is created on secure hosting
too; asking for another placement is refused (422) and recorded as a security event
(authz.branch_placement_refused), and the cell refuses any copy from secure hosting into an instance that is
not on secure hosting.
Reset: back to the parent, same connection details
Section titled “Reset: back to the parent, same connection details”Reset copies the parent’s current data into the branch again. The branch stays the same instance, so its hostname, port and credentials do not change and your application reconnects without a config change. A schema-only branch resets to the parent’s schema without rows.
Before the copy, reset removes what the branch’s own role created, so objects that exist only on the branch do not survive:
- PostgreSQL: every schema the database role owns except
publicand the platform’szb_*schemas, then the role’s tables, views, materialized views, sequences, functions, procedures and types inpublic. Extensions and objects that belong to other roles are left alone. - Valkey and Redis: the database is flushed, then every key is copied with its TTL.
Reset is available for PostgreSQL, Valkey and Redis branches. For other engines, delete the branch and create it again. The branch and its parent must be running, and only one operation runs on a branch at a time (409 otherwise).
Promote: the branch replaces the parent
Section titled “Promote: the branch replaces the parent”Promote takes a pre-change backup of the parent first. When that backup has completed, the platform copies the branch into the parent the same way a reset does (the parent’s own objects are removed first), so the parent ends up equal to the branch. The parent keeps its endpoint and credentials, and the branch stays until you delete it. If the backup fails, nothing is copied and the parent is not changed. To undo a promote, restore the parent from the pre-change backup (its id is on the operation).
Promote needs an organization owner or admin (instances:delete on the parent’s project), a second factor
completed in the last 15 minutes, and both names typed. A schema-only branch is never promoted, because it would
empty the parent’s tables. Promote is available for PostgreSQL, Valkey and Redis. It is not available through MCP.
To bring only a branch’s schema to its parent (new columns, indexes, constraints) without replacing the parent’s data, use Safe schema changes: the DDL with a lock-risk lint, applied in one transaction, with a team lead’s approval when the team requires it.
Delete
Section titled “Delete”Deleting a branch needs an owner or admin (instances:delete), a recent second factor and the branch’s name
typed. It is refused while the branch has branches of its own or an operation (a copy, reset or promote) runs on
it. The branch’s backups are kept for your plan’s retention window, as for any instance. The delete route only
accepts a branch of the parent in the URL, so it can never delete the parent.
Anonymized branches (PostgreSQL)
Section titled “Anonymized branches (PostgreSQL)”An anonymized branch is a full copy whose personal data is masked before anyone can connect to it. Use it to give developers realistic data from a database that holds personal or health information.
- Masking rules. On the parent’s Branches page (or
PUT /v1/orgs/{org}/instances/{id}/masking-rules), list the columns to mask and how:null(remove),redact([REDACTED]),pseudonym(zb-and a keyed hash: the same value gets the same pseudonym within the branch),email(user-<hash>@example.invalid),phone(a fictional555-01number),zip3(first three characters,021**) oryear_only(dates and timestamps keep only the year). Rules hold names only: plain identifiers (letters, digits,_,$), never a system schema, at most 500. Suggest lists columns that look like personal data from their names and types; the query runs inside your database and only names and types come back, no value is read. - Create the branch with Mask personal data (
"mask": true). The branch is a copy (never a volume snapshot), and the copy’s own Job then masks it with PostgreSQL Anonymizer inside the cell, as the branch’s superuser. It compares SHA-256 digests of every masked column before and after masking, inside the database, and also checks materialized views (refreshed) and planner statistics (rebuilt): only the counts leave the cell. The branch’s credentials, console and data features stay closed (409) until that proof arrives. - If masking fails, or its report does not prove exactly the branch’s rules, the branch is deleted at once with no retention, and its credentials were never revealed.
Masked branches cannot be reset in place, promoted or branched again: delete one and create a new masked branch instead. The masking labels stay on the branch and its own role cannot change them. Masked branches need the cell to run the extended PostgreSQL image that ships PostgreSQL Anonymizer; on a cell without it, masking fails and the branch is deleted.
Leaving secure hosting. A branch of a database on secure hosting stays on secure hosting. Only a masked branch
whose masking completed can leave it, through POST …/branches/{branch_id}/placement
{placement: "shared", confirm_branch_name, attestation: {safe_harbor: {…18 identifiers: true}, no_actual_knowledge: true}}:
an organization owner or admin, signed in to the portal (no API key) with a second factor completed in the
last 15 minutes, attests that every HIPAA Safe Harbor identifier is removed. Every refusal is audited and recorded
as authz.branch_placement_release_refused, and an unmasked branch of a secure database is always refused (422),
through this call and through PATCH alike.
In the portal
Section titled “In the portal”Open a database and choose Branches in the Operations group. The page lists every branch with its lineage (branches of branches are indented), whether it holds a full copy or only the schema, its storage compared with the parent, its price per hour and month, and its last operation. Create branch, Reset, Promote and Delete ask for the names described above.
With the zb CLI
Section titled “With the zb CLI”zb branch create inst_01main --name feat-login # full copyzb branch create inst_01main --name feat-schema --schema-only # schema without rows (PostgreSQL)zb branch list inst_01main --recursive # lineage, data, storage delta, price/hzb branch get inst_01main inst_01branch # the branch and its operationszb branch reset inst_01main inst_01branch # asks you to type the branch namezb branch promote inst_01main inst_01branch # asks for the parent's and the branch's nameszb branch delete inst_01main inst_01branch --confirm feat-loginEvery command takes --json. reset and delete take --confirm <branch name>, promote takes
--confirm <parent name> --confirm-branch <branch name> for scripts; without them the CLI asks. --yes skips the
reset prompt only.
With the API
Section titled “With the API”| Call | Needs |
|---|---|
GET /v1/orgs/{org}/instances/{id}/branches?recursive=true | instances:read |
POST /v1/orgs/{org}/instances/{id}/branches {name, data?: "full" | "schema_only", git_branch?, placement?, mask?} | instances:create on the project (202) |
GET /v1/orgs/{org}/instances/{id}/branches/{branch_id} | instances:read; includes the last 20 operations |
POST …/branches/{branch_id}/reset {confirm_name?} | instances:operate (202, an operation) |
POST …/branches/{branch_id}/promote {confirm_name, confirm_branch_name} | instances:delete and a recent second factor (202, an operation) |
DELETE …/branches/{branch_id}?confirm_name= | instances:delete and a recent second factor (202) |
GET / PUT /v1/orgs/{org}/instances/{id}/masking-rules {rules, revision?} | instances:read / instances:operate |
GET …/masking-rules/suggestions | instances:read; the instance must be running |
POST …/branches/{branch_id}/placement | org owner or admin, a person with a recent second factor, the Safe Harbor attestation (202) |
Every branch in a list or get response is the instance plus a branch object: parent_id, parent_name,
depth, data, method, resets, reset_at, storage_used_bytes, parent_storage_used_bytes,
storage_delta_bytes, price_cents_per_hour, data_status, the latest operation and, for an anonymized branch, masking. An operation moves through waiting
(the branch is starting), backing_up (promote only), copying, then completed or failed with an error.
The copy itself is a migration on the target instance (migration_id), so its progress also shows on that
instance’s Migrate in page.
Every lookup is scoped to the organization in the URL: a branch or parent of another organization is a 404, and a
key of one organization calling another organization’s URL is refused and recorded (authz.cross_org_access).
Creating, resetting, promoting and deleting branches are written to the audit log; promote and delete are also
security events (data.branch_promote_requested, data.branch_deleted).
With MCP
Section titled “With MCP”The Databasezy MCP server has list_branches, create_branch, reset_branch and delete_branch. The last two
need confirm=true after you confirm with the person. There is no promote tool: a person promotes in the portal or
with zb branch promote.