# Database branches (preview databases)

A branch is a **database made from the project's schema**. With one per git branch, that branch's preview deployments
use the branch instead of the production database. From the Pro plan, up to 3 per project (10 on Enterprise).

- When it is made, the project's migration history (what `apply_migrations` and `oneend db push` applied) is replayed
  in order, then the seed SQL if there is one. **Rows are not copied.**
- A branch is a project with a ref of its own. Use the `ref` from `list_branches` with `run_sql`, `get_project_keys`,
  `get_database_connection` and every other tool. Its address, keys, users and files are its own too.
- A preview deployed from the branch's git branch gets the branch's `SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_URL`,
  `SUPABASE_ANON_KEY`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `DATABASE_URL`,
  `POSTGRES_URL`, `DIRECT_URL` and `ONEEND_DB_BRANCH` in its environment. Preview variables holding the production
  project's address or keys are switched to the branch's as well.
- `merge_branch` applies the migrations only the branch has to production. So change a branch's schema with
  `apply_migrations { ref: <branch ref> }`, not `run_sql`.
- Deleting the git branch or closing its pull request deletes the branch. So does its keep period (14 days by default)
  running out after the last deployment. A branch over its size limit (1GB by default) is paused.

```
create_branch { ref, git_branch: "feature/login" }
list_branches { ref }
apply_migrations { ref: "<branch ref>", migrations: [{ version: "20261005000000", name: "add_profiles", sql: "..." }] }
merge_branch { ref, name: "feature-login" }
reset_branch { ref, name: "feature-login", confirm: "feature-login" }
delete_branch { ref, name: "feature-login", confirm: "feature-login" }
set_branching { ref, automatic: true, seed_sql: "insert into plans (code) values ('free');", lifetime_days: 14 }
```

With `automatic` on in `set_branching`, a branch is made by itself for every git branch deployed as a preview.

**Billing:** a branch's database is billed as database storage, and while it exists as 0.25GB of server memory an hour
(`runtime_gb_hour`), to the project's organisation. Branches are not in the nightly backup.

Over HTTP: `GET /branches`, `POST /branches`, `POST /branches/<name>/merge`, `POST /branches/<name>/reset`,
`DELETE /branches/<name>`, `PUT /branching`.

---

https://end.blackall.ai/docs/branches?lang=en