> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Branches for previews and agents > Give every pull request and every agent task a database it can’t hurt production with, and try migrations there first. > [!NOTE] > > **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release. ## Goal Run a pull request preview or an agent task against its own database, so a bad migration or a mistake fails there and never in production. ## Prerequisites * A PostgreSQL database connected to your app * For agents: an agent connection that is allowed to work on databases ## Workflow **Step 1** Open a pull request. The preview gets a database of its own, empty and filled by your seed command, and never production’s connection details. **Step 2** The release command runs your migrations on that database first. A destructive migration should fail there, before it gets anywhere near production. **Step 3** Test the preview. If an attempt goes wrong, reset the branch instead of making a new one. **Step 4** Merge the pull request. Your code is promoted and the data is not. The preview’s database is deleted when the pull request merges or closes. ## What previews get by default An app preview gets an empty or seeded database. That doesn’t change when branches arrive. Copying production data into a preview is a setting you choose per project. It is off by default, only the project owner can switch it on, and it is coming with full-stack branches. An agent can ask for a copy but can never switch the setting on. A data copy of a production database made by an agent always needs the owner’s approval. ## The pull request flow * A pull request opens, or an agent starts a task that needs its own copy of the app. * The preview’s database is created: empty and seeded by default, or a branch made from now once your project allows copies. A branch for a pull request carries the pull request number (`pr:142`). * The preview’s `DATABASE_URL` points at that database’s Shared connections address, so it copes with the database sleeping between pushes. * Migrations run on it first. The agent or your tests use its address. * Reset it between attempts: `stackshift db branch reset shop-db/pr-142`. * When the pull request merges, the code is promoted. The data never is. The branch is deleted. A closed pull request deletes it too, and an unused one expires after 24 hours with a warning in the pull request. ## Safety * Scheduled jobs are paused on a branch, so a copy can’t send emails or charge cards on production’s behalf. * Subscriptions and replication links to other databases are switched off, and other database logins get passwords nobody knows. The branch page lists any outside servers your data can reach so you can check them. * A branch has its own address and password. It is never given production’s. * Previews never receive production connection details, and mail and payments are blocked in previews. * An agent needs the owner’s approval to make a branch the main database, to delete a branch, or to copy production data. * Never make a pull request branch’s data the main database. The branch is a test copy, and anything on it that matters belongs in a migration. ## Agent playbook Agents work through the actions below, each proposed with `operation_propose` and shown to the owner as usual. Inspect first with `database.branch.inspect`, which shows the tree, how far a branch has drifted, its remaining life and its state. * Try the migration on a branch first: `database.branch.create`, then point the app or tests at the branch’s address. * Reset the branch between attempts with `database.branch.reset` instead of making new ones. * Delete branches when you’re done with `database.branch.delete`. They expire on their own after 24 hours, and `database.branch.extend` keeps one longer if a task needs it. * Never promote a pull request branch’s data with `database.branch.promote`. Code is promoted, data is not. * On Dedicated, quote the hourly price to the owner before creating a branch. * Before a batch job on a database that sleeps, wake it with `database.wake`. Turn sleep on or off with `database.sleep.set`. * If a connection fails with `57P03` (“the database is waking up”), wait a few seconds and retry. ```bash One task's lifecycle theme={null} stackshift db branch create shop-db --name try-reindex --ttl 24h --wait -o json stackshift db branch url shop-db/try-reindex stackshift db branch reset shop-db/try-reindex stackshift db branch delete shop-db/try-reindex ``` ## Availability Branches are rolling out. If your database page doesn’t show Branches yet, it isn’t switched on for your account. Copies of production data for app previews are coming with full-stack branches. ## Expected result > [!TIP] > > Every pull request or task works on its own data. Production’s database is never written to by a preview or an agent’s experiment, and the temporary databases clean themselves up. ## Common failures > [!WARNING] > > * An agent’s request is waiting: making a branch the main database, deleting a branch and copying production data all wait for the owner to approve. > * `402 plan_limit` for an agent: it has left branches behind. Delete the ones you don’t need. They expire after 24 hours on their own. > * A preview has no production data: this is the default. Copies of production data are a per-project owner setting that is coming. > * A migration passed on the branch and failed on main: the branch is a copy from the moment it was made. Reset it to get fresh data and run again. > * The first query after a quiet spell fails with `57P03`: retry it, and set your driver’s pool as described in Sleep when idle. ## Related guides > [card] [Branches](https://docs.stackshift.cloud/databases/branches.md) > > A copy of your database you can change freely. It has its own address and password, and sleeps when nobody’s using it. > [card] [Sleep when idle](https://docs.stackshift.cloud/databases/sleep-when-idle.md) > > A database nobody is using goes to sleep and wakes on the next connection. Its address, password and data stay the same. > [card] [Application previews and promotion](https://docs.stackshift.cloud/ai-features/application-previews.md) > > Review pinned code in a dedicated Application with fresh PostgreSQL data, then approve cleanup or a separate parent release. > [card] [Connect your coding agent](https://docs.stackshift.cloud/ai-features/agent-connections.md) > > Connect an external client, choose its access and inspect its work in StackShift. > [card] [What agents can do](https://docs.stackshift.cloud/ai-features/agent-actions.md) > > Every action Stackie and connected agents can take, and when each one waits for you. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.