Skip to content

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.

ChoiceWhat the branch getsEngines
Full copy (default)The parent’s schema and rows as they are when the copy runsEvery engine
Schema onlyEvery table, index, view, function and type, no rows; sequences start at their initial valuesPostgreSQL

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 public and the platform’s zb_* schemas, then the role’s tables, views, materialized views, sequences, functions, procedures and types in public. 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 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.

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.

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.

  1. 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 fictional 555-01 number), zip3 (first three characters, 021**) or year_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.
  2. 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.
  3. 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.

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.

Terminal
zb branch create inst_01main --name feat-login # full copy
zb branch create inst_01main --name feat-schema --schema-only # schema without rows (PostgreSQL)
zb branch list inst_01main --recursive # lineage, data, storage delta, price/h
zb branch get inst_01main inst_01branch # the branch and its operations
zb branch reset inst_01main inst_01branch # asks you to type the branch name
zb branch promote inst_01main inst_01branch # asks for the parent's and the branch's names
zb branch delete inst_01main inst_01branch --confirm feat-login

Every 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.

CallNeeds
GET /v1/orgs/{org}/instances/{id}/branches?recursive=trueinstances: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/suggestionsinstances:read; the instance must be running
POST …/branches/{branch_id}/placementorg 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).

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.