Upgrade misomoon

New versions are listed in the changelog and on the releases page. Read the notes for every version between yours and the new one before you upgrade.

An upgrade keeps your data. The deploy applies new migrations to every database, and migrations only add to the schema. To roll back, deploy the previous version again. The extra columns or tables that a newer migration added stay, and the older code ignores them.

#Upgrade a command-line install

1. Get the new version:

   shCopy

   git pull
   pnpm install

   If you keep your own fork, merge the upstream main branch into it instead. Keep your database ids in apps/api/wrangler.jsonc.

2. Deploy:

   shCopy

   pnpm --filter @misomoon/api run deploy

   The deploy applies new migrations, and then deploys the Worker.

#Upgrade a Deploy to Cloudflare install

The button copied the deploy bundle into a repository that you own. Cloudflare deploys that repository again each time you push to it. To upgrade, copy the new bundle into your repository, and keep your own wrangler.jsonc, which holds your database ids.

1. Clone your repository, and go into it:

   shCopy

   git clone https://github.com/<you>/<your-repo>.git
   cd <your-repo>

2. Download the latest bundle:

   shCopy

   curl -L https://github.com/jackzard/misomoon/archive/refs/heads/deploy.tar.gz | tar xz

3. Copy it over your files, but keep your wrangler.jsonc:

   shCopy

   rsync -a --exclude wrangler.jsonc misomoon-deploy/misomoon/ ./
   rm -rf misomoon-deploy

4. Compare the new wrangler.jsonc with yours:

   shCopy

   curl -sL https://raw.githubusercontent.com/jackzard/misomoon/deploy/misomoon/wrangler.jsonc | diff wrangler.jsonc -

   Copy new settings into your file, such as a new variable or a new compatibility_date. Don't copy the database_id values.

5. Commit and push:

   shCopy

   git add -A
   git commit -m "Upgrade misomoon"
   git push

   Cloudflare builds and deploys the push. The deploy script applies the new migrations first.

#Scale the shards

Events and visits live in the shard databases. A D1 database holds up to 10 GB. When a shard reaches SHARD_SOFT_LIMIT_MB (8,000 MB by default), it stops taking new days of data, and its sites continue on another shard. Add shards before every shard is near the limit. To see the size of each database, open Storage & Databases > D1 in the Cloudflare dashboard.

More shards also spread the writes. One D1 database handles one write at a time, so a busy instance with many sites is faster with more shards.

#Command-line installs

Set SHARD_COUNT to the number of shards you want, and deploy:

SHARD_COUNT=4 pnpm --filter @misomoon/api run deploy

The deploy creates the new databases, binds them, migrates them, and deploys. A new shard registers itself on the next request, and it takes most new sites because it has the most free space. To see the plan without changing anything, add --plan:

SHARD_COUNT=4 pnpm --filter @misomoon/api run deploy -- --plan

To remove shards, deploy with a smaller SHARD_COUNT. The extra shards are marked retiring, and the Worker moves their data to the other shards every 5 minutes. Run the same deploy again later. It unbinds each retiring shard after it is empty. The script never deletes a database. Delete an empty one yourself with wrangler d1 delete <name>.

#Deploy to Cloudflare installs

1. Create a database:

   shCopy

   npx wrangler d1 create misomoon-shard-2

   If your other databases are in the EU jurisdiction, add --jurisdiction eu.

2. Add it to d1_databases in your wrangler.jsonc, with the id that the command printed:

   jsoncCopy

   { "binding": "SHARD_2", "database_name": "misomoon-shard-2", "database_id": "<id>", "migrations_dir": "migrations/shard" }

3. Commit and push. The deploy script migrates every SHARD_* binding, and the new shard registers itself.

To remove a shard from this kind of install, use a command-line install, because the data has to move first.