/xata

name: xata
description: "Load when working with Xata Postgres branches: forking a branch, building or testing dbt models on a branch, wiring dbt to a branch's credentials, diffing two branches, or the pre-merge impact report. Covers create_xata_branch, delete_xata_branch, get_dbt_profile, xata_branch_diff, schema_diff_branches, and pgroll migrations."
type: skill

Xata branches: build dbt on isolated branches, review, merge

Xata is a Postgres-at-scale platform. A branch is a copy-on-write clone of a Postgres database — a full-data fork in under a second at no storage cost. Each branch is a standard Postgres endpoint. Build and validate every model change on a branch, then a human merges to production. Never build on `main` or `staging`.

Connect to a workspace

Register a Xata workspace as a `xata`-type connection, not a raw `postgres` URL. The stored secret is the control-plane API key (`xata_api_key`), with `xata_organization`, `xata_project`, and `xata_database`. The gateway resolves each branch's Postgres endpoint (`<branchID>.<region>.xata.tech`) server-side.

Do not paste a `postgresql://...xata.tech/...` URL as a connection. One workspace connection addresses every branch.

Branch lifecycle

Fork a branch with `create_xata_branch(connection_name, project, branch_name, parent_branch)`. This is the only way to create a branch. Name it `agent_<model>_<YYYYMMDD>` using `[A-Za-z0-9_.-]` only — no `/`. Fork from `staging` (or `main`) to get realistic data at zero copy cost.

List branches with `xata_list_branches(connection_name, project)` before creating, to avoid duplicate branches.

Delete a branch with `delete_xata_branch(connection_name, project, branch_name)` only after a human confirms the change merged. `main`/`staging`/`prod` cannot be deleted through this tool.

Build dbt models on a branch

Build or change a model on a branch — never on `main` or `staging`.

1. Fork a branch with `create_xata_branch` (above). 2. Wire dbt with `get_dbt_profile(connection_name, branch, profile, target)`. It returns a shell COMMAND, not credentials. Run the command from the dbt project directory. It writes the branch's Postgres credentials into `profiles.yml`, upserting that one target and keeping your other targets. 3. Build with `dbt run --target <target>`. dbt writes tables to the branch. 4. Test with `dbt test --target <target>`. 5. Produce the review report with `xata_branch_diff(connection_name, base_branch, compare_branch, format="html")`. Share the returned URL. 6. A human merges. Then delete the branch with `delete_xata_branch`.

Do not read or print `profiles.yml` — it holds the live branch password. Do not paste credentials into committed files, the diff report, or the handoff.

`get_dbt_profile` refuses `main`/`staging`/`prod`; it issues write credentials only for agent-created branches. Write with `dbt run`. `query_database` is governed read-only and blocks DDL/DML — use it (and `explore_table`, `schema_ddl`, `schema_link`) only to inspect any branch.

Diff two branches

Call `xata_branch_diff(connection_name, base_branch, compare_branch)` to compare two branches from one workspace connection. The gateway swaps the branch on the stored credential and diffs the two live schemas. Add `format="html"` to render the review-ready pre-merge impact report and return a shareable URL.

Call `schema_diff_branches(base_connection, compare_connection)` when the two branches are registered as two separate connections instead.

Do not use `schema_diff` to compare branches. `schema_diff` compares one connection against its own cached snapshot, not against another connection.

Pre-merge impact workflow

Run this before a feature branch merges into the base branch.

1. Diff the branches with `xata_branch_diff(connection_name, base, feature, format="html")`. 2. For each removed column, find every dbt model whose SQL selects that column from the changed source table. Each such model is a breaking change. 3. For each removed column, find every dbt test (`accepted_values`, `not_null`, `unique`, `relationships`) on that column. Each such test is a breaking change. 4. For each type change, flag models that use the column as a warning. Flag any `accepted_values` test on that column as breaking when the new type is numeric and the listed values are strings. 5. Propagate downstream: any model that `ref()`s a breaking model is a warning, because it cannot build once its parent fails. 6. Report a verdict. Any breaking change means do not merge.

The static report is a superset of what a dbt run surfaces. A dbt run stops at the first failed node in a chain and skips the rest. The static report lists every break, not just the first one dbt hits.

pgroll migrations

Xata applies schema changes with pgroll (`xata roll`). pgroll runs expand then contract. During expand it keeps the old and new columns both live, exposed through versioned view schemas named `public_<migration_name>`. Applications select a version with `SET search_path = 'public_<migration_name>'`.

When a branch under review uses pgroll expand/contract, the old column still exists until `pgroll complete` runs. Recommend the expand/contract path as the safe remediation: it lets the warehouse migrate to the new column before the old one is dropped, so the merge does not break the pipeline.

Introspect only the application schema (for example `raw`) when diffing. Ignore pgroll's internal `pgroll` schema and its `<schema>_<migration>` version schemas.