# Xata > Load when working with Xata Postgres branches: connecting to a branch, diffing two branches, or checking whether an upstream branch's schema change breaks a dbt project or pipeline before it merges. Covers branch connections, schema_diff_branches, pgroll migrations, and the pre-merge impact report. - Skill: `signalpilot-labs/xata-3` (Agent Skill) - Install (CLI): `npx skillmds@latest add signalpilot-labs/xata-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/signalpilot-labs/xata-3/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: signalpilot-labs (https://skillmd.com/u/signalpilot-labs) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/signalpilot-labs/xata-3 --- # Xata branches and pre-merge impact analysis Xata is a Postgres-at-scale platform. Branches are copy-on-write copies of a Postgres database. Each branch is a standard Postgres endpoint with its own connection string. Treat a Xata branch as a normal `postgres` connection. ## Connect to a workspace Register a Xata workspace as a `xata`-type connection, not as a raw `postgres` URL. The stored secret is a scoped Xata API key, not a database connection string. The gateway resolves the per-branch Postgres endpoint server-side. Set the workspace, region, database, and default branch on the connection. Do not paste a `postgresql://...xata.sh/...` URL as a connection. Store the API key on a `xata` connection and let the gateway build the endpoint. One workspace connection addresses every 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. Use this for the pre-merge gate. 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. ## List branches Call `xata_list_branches(connection_name, project)` to list the branches in a Xata project. Each branch shows its name, id, and parent branch. ## Pre-merge impact workflow Run this before a feature branch merges into the base branch. 1. Diff the branches with `schema_diff_branches(base, feature)`. 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_`. Applications select a version with `SET search_path = 'public_'`. 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 `_` version schemas.