Give schema pull requests their own PlanetScale branch

When a pull request is opened in our GitHub repository, provision a matching PlanetScale development branch so reviewers get an isolated database to test schema changes against. Trigger this workflow from a GitHub webhook on the pull request opened event.

Start by fetching the pull request from GitHub with Get a Pull Request so you have its title, body, and head branch name. Our GitHub integration has no per-file pull request diff operation, so you cannot look at a changed files list. Judge whether the change is schema related from the title, body, and head branch name alone. That judgement is the whole point of this workflow, so take it seriously.

Treat it as schema related when there is a concrete signal, for example a head branch named something like add-orders-table, migrate-users, or db/backfill-index; a title or body that mentions a migration, a new or dropped table, a column, an index, a foreign key, or a backfill; or a body that references migration files or an ORM schema file such as a Prisma, Drizzle, or Atlas schema. Do not infer schema work from vague wording alone. If there is no concrete signal, treat the pull request as not schema related.

If the pull request is not schema related, stop immediately and do nothing. Do not create a PlanetScale branch and do not post a comment of any kind, not even one saying it was skipped. Silence on unrelated pull requests is a requirement, not a nicety.

If it is schema related, create the database branch with PlanetScale Create a branch in our organization and database, using our production branch as the parent so the new branch starts from the real production schema. Follow the community convention that the git branch name and the PlanetScale branch name should match: name the new branch after the pull request head branch. If the head branch contains characters PlanetScale will not accept, such as slashes in db/add-index, replace them with dashes and use that as the name. Before creating, call Get a branch for the intended name; if a branch with that name already exists, reuse it rather than creating a duplicate or failing, which keeps reopened pull requests and repeat runs clean.

Branch creation is asynchronous, so confirm the branch actually reached ready state by calling PlanetScale Get a branch and checking its ready status, retrying a few times with a short wait between attempts. If it is still not ready after a reasonable number of attempts, do not claim it is ready; say in the comment that the branch was created and is still preparing.

Once the branch is ready, post a single comment on the pull request with GitHub Create an Issue Comment. Name the new PlanetScale branch exactly, say it was branched from our production branch, and give the next step: apply the migrations to that branch, then open a deploy request to roll the schema change into production once the change has been reviewed. Keep the comment short and useful to a reviewer skimming the thread.

Never put database credentials into the pull request comment. Do not create or request a branch password, and never include a connection string, host, username, or password, even if a PlanetScale response contains one. Pull request comments are visible to everyone with access to the repository, so the comment must carry only the branch name and instructions. Reviewers get their own credentials from PlanetScale directly.