---
title: "Windsurf - Xata"
description: "Use Windsurf Cascade and Flows with repeatable Xata branch workflows."
source: "https://xata.io/docs/ai-agents/windsurf"
---

Skip to main content

# ​Windsurf with Xata

Windsurf’s Cascade and Flows can handle multi-step coding tasks. Pair them with Xata branches so every flow has a safe Postgres target for migrations, tests, and database inspection.

## ​What Windsurf is good for with Xata

- Turning repeated database setup into a Flow.
- Making multi-file application and schema changes in one IDE session.
- Running terminal commands while preserving project context.
- Debugging application behavior against a realistic branch.

## ​Quick start

1. Create a branch for the Windsurf task.

```
xata branch create --name windsurf-task --parent-branch `xata branch get id`
```

2. Store the branch URL where the app reads local environment variables.

```
echo "DATABASE_URL=$(xata branch url windsurf-task)" >> .env.local
```

3. Open the project in Windsurf.
4. Ask Cascade to use the local branch for all database commands.

## ​Recommended Xata setup

Create a Flow for the database setup you repeat often: create branch, print branch URL, run migrations, run tests, and report branch status. Keep destructive operations behind explicit approval.

## ​Example prompts

- “Create a Flow that prepares a Xata branch, runs migrations, runs tests, and reports results.”
- “Use the Xata branch URL in `.env.local`; do not use production credentials.”
- “Apply this schema change to the branch and explain the SQL.”
- “Debug the failing test by inspecting the branch schema and application logs.”
- “Add cleanup instructions for the temporary branch.”

## ​Common workflows

### ​Flow-based branch setup

1. Create a Flow with Xata CLI setup commands.
2. Add project migration and test commands.
3. Ask Cascade to run the Flow before implementation.
4. Review the Flow output before merging changes.

### ​Migration testing

1. Create a branch from the current parent.
2. Ask Cascade to apply the migration.
3. Run application tests against the branch.
4. Ask Cascade to summarize changed tables and columns.

## ​Tips

- Keep the branch name visible in the Flow output.
- Ask Cascade to pause before deleting branches or changing credentials.
- Use anonymized clones for flows that need production-like data.
- Keep `.env.local` uncommitted.

## ​Troubleshooting

| Issue                                 | Fix                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------- |
| Cascade forgets the database target   | Put the branch name and environment file path in the Flow description.     |
| A Flow runs against stale credentials | Regenerate the branch URL and restart the local dev server.                |
| Generated SQL is too broad            | Ask Cascade to split schema and data changes into separate reviewed steps. |

## ​Related Xata docs

- [Instant Branching](/docs/core-concepts/branching)
- [Data Anonymization](/docs/core-concepts/anonymization)
- [Schema Changes](/docs/core-concepts/schema-changes)
- [Branch commands](/docs/cli/branch)

Was this page helpful?