Preview databases per pull request
A branch is a copy of a project with its own URL and API keys. Create one per pull request in CI, point the preview at it, and let it expire or delete it at merge.
One pull request = one database#
aura branch create clones a PostgreSQL project (schema, row level security policies, functions, triggers, views and rows) into a new project with its own URL and API keys. A pull request can run its migration there, and reviewers can try the result, without any contention on the source project. The full list of what is and is not cloned, and the limits, are in database branches.
A branch is a copy made when you create it, in time proportional to the data (14 seconds for 333 MB on the local test stack). It is not a copy-on-write clone, and it does not follow the source afterwards.
In CI#
There is no GitHub Action to install: the CLI does the work. Authenticate with a Personal Access Token (aura login --token), then create the branch from the project you test against and keep what the preview needs. Save each snippet as a script of your pipeline:
aura login --token "$AURA_PAT"
aura branch create "pr-$PR_NUMBER" --from "$AURA_PROJECT_ID" --ttl 3d --json > branch.json
# branch.json: id, slug, url, anon_key, service_role_key, expires_at
aura login --token "$AURA_PAT"
aura branch delete "pr-$PR_NUMBER" --from "$AURA_PROJECT_ID" --force
The keys are printed only once, when the branch is created: store them in the job (or as secrets of the preview deployment) right then. To run the pull request's migrations on the branch, link the folder to it and push: aura link --project-id <branch id> then aura db push.
The aura branch commands were run against a local stack; aura login --token is the login of the CI recipes in deployment. The GitHub or GitLab workflow around them is yours to write.
What the branch contains#
The branch has the rows of the source (add --no-data for the schema only), including any personal data they hold: there is no anonymization. Create the branch from a staging project, not from production, if the preview must not see real data. Auth users, storage objects, edge functions and secrets are not cloned; seed them in your preview setup.
TTL and quotas#
A branch lives 72 hours by default, up to 30 days (--ttl). Expired branches are deleted automatically, and so is a branch whose creation fails. A branch does not count against your project limit; it counts against the limit of active branches of your plan (1 on Free, 10 on Pro, 25 on Team), see limits. Past the limit, aura branch create fails with BRANCH_LIMIT_REACHED: delete a branch or wait for its TTL.