# Scaling the database

> One D1 database is the default and is enough for most teams. When you outgrow it, scaled mode spreads documents over many databases, the way planpa.ge runs.

Cloudflare D1 caps each database at [10 GB](https://developers.cloudflare.com/d1/platform/limits/). planpage can run on one database, or spread documents over as many as it needs. Teams, workspaces, sharing and everything else work the same either way; only where the rows are kept changes.

## Single database (the default)

A new install keeps everything in the one database you created in [Install](https://planpa.ge/docs/self-host-install.md): accounts, teams, workspaces, documents, comments and activity. There is nothing to set up.

The heavy parts already live elsewhere. Every version's text is kept in R2, as are uploaded images and rendered diagrams, and the cron moves activity older than 90 days out to R2 as well. So the database holds mostly the current documents and their comments. For scale: planpa.ge's own database, with version text still in it, was 34 MB in October 2026.

You can see how big yours is, and how fast it's growing, on **Admin → Databases**. It raises an alert there when the database passes 2 GB, long before the cap.

## Scaled mode

In scaled mode, planpage adds D1 databases by itself and places documents across them:

- Your first database keeps accounts, teams, workspaces, billing and the index of which database holds each document. It also keeps the documents written before you turned scaling on, apart from teams' documents (and, with billing on, those of people on a paid plan), which move to their own database over the next few cron runs.
- Each team gets its own database for new documents. Personal workspaces share pool databases.
- A database stops taking new documents at 4 GB (you can change this), and its owner moves on to a fresh one. If a database's existing documents keep growing past 7 GB, the busiest move off it.
- A few empty databases are kept ready (two, unless you change it), so a new team never waits for one.
- **Admin → Databases** shows each database, lets you add more, and moves documents between them. A document being moved pauses saving for a second or two; reading it doesn't pause.

New databases get their tables from the Worker itself, so `pnpm selfhost:migrate` still only migrates your first database.

### What it needs

A Worker can only reach a D1 database through a binding in the config it was deployed with. So adding a database means deploying again, and planpage starts that deploy itself through a [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) deploy hook. You need:

- your copy of planpage in a GitHub or GitLab repository that Workers Builds can build, with your `wrangler.selfhost.jsonc` committed to it (it's ignored by default; add it with `git add -f apps/web/wrangler.selfhost.jsonc`);
- a Cloudflare API token with **Account → D1 → Edit** on your account, and nothing else.

### Turn it on

1. In the Cloudflare dashboard, open your Worker, then **Settings → Builds**, and connect your repository:

   | Setting | Value |
   | --- | --- |
   | Branch | The branch you deploy from |
   | Root directory | `apps/web` |
   | Build command | `pnpm install --frozen-lockfile` |
   | Deploy command | `pnpm selfhost:migrate && pnpm selfhost:deploy` |

   Workers Builds expects the Worker's name in `apps/web/wrangler.jsonc`, which is planpa.ge's config. Wrangler takes your Worker's name when it deploys, so the build still works. If Workers Builds opens a pull request to rename the Worker in that file, close it.

2. Under **Deploy Hooks** on the same page, create a hook for that branch and copy its URL.
3. Create the API token under **My Profile → API Tokens → Create Token → Custom token**, with the one permission above.
4. In planpage, open **Admin → System settings → Databases** and fill in:
   - **Cloudflare account ID**: from the dashboard's account home page;
   - **Cloudflare API token**: the token from step 3;
   - **Deploy hook URL**: the URL from step 2;
   - optionally the database name prefix (new databases are named `planpage-db-0001` and so on) and where they live.
5. Turn on **Add databases automatically** and save.

Within a few minutes the cron creates the first ready databases, and a build binds them. You can watch each step under **Admin → Databases → Activity**, or press **Add databases** there to start straight away.

### How deploys change

`pnpm selfhost:deploy` reads the list of databases from your first database and binds every one of them before deploying. If it can't read that list, it stops rather than deploy a Worker that can't reach some documents. Keep deploying through `pnpm selfhost:deploy` (or the build above), never a bare `wrangler deploy`.

A Worker holds about 5,000 D1 bindings. **Admin → Databases** warns at 2,500. That's 10 TB of documents at 4 GB each, so it's unlikely to matter for a self-hosted copy.

### Turning it off

Turning off **Add databases automatically** stops new databases being created. Databases already in use keep serving their documents, so leave them bound. Documents can be moved back onto fewer databases from **Admin → Databases → Move documents**.

## Plans that end

With billing off, which is the default for self-hosting, no team's plan ever ends, so nothing is ever locked or archived. If you turn billing on, a team whose plan has been over for 90 days is archived: each workspace's download is saved, and its documents are stored in R2 until the team renews. See [Workspaces](https://planpa.ge/docs/workspaces.md#when-a-plan-ends).
