Skip to main content
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

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.
2
The release command runs your migrations on that database first. A destructive migration should fail there, before it gets anywhere near production.
3
Test the preview. If an attempt goes wrong, reset the branch instead of making a new one.
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.
One task's lifecycle

​
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

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

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

Branches

A copy of your database you can change freely. It has its own address and password, and sleeps when nobody’s using it.

Sleep when idle

A database nobody is using goes to sleep and wakes on the next connection. Its address, password and data stay the same.

Application previews and promotion

Review pinned code in a dedicated Application with fresh PostgreSQL data, then approve cleanup or a separate parent release.

Connect your coding agent

Connect an external client, choose its access and inspect its work in StackShift.

What agents can do

Every action Stackie and connected agents can take, and when each one waits for you.