Docs idea: a "before you upgrade" checklist built from seven umami migration-failure threads

Open Beginner friendly
#50 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
70/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown
Domain
documentation

Research direction

Read the seven migration-failure threads linked from the issue and verify their details before turning the checklist into an Upgrading docs section. The payload names no documentation file or test, so locate the relevant upgrade docs in the repository. Done when the section presents a sourced checklist and recovery guidance consistent with those reports.

Written by the indexing model from the issue text.

Description

I read seven threads in Umami's issue tracker where an upgrade stopped on a failed Prisma migration; here is what they share, as a checklist for an "Upgrading" docs section. Edit it or ignore it.

Before you upgrade

  1. Look for a half-applied migration: check _prisma_migrations for one that started but never finished; it blocks every later migration.
  2. Check the database: on Postgres 12 or older the 1.39 migrations did not run, so account_uuid was missing. On MariaDB, the visit-id migration (05) uses a UUID function it lacks.
  3. Check the size of the website events table: migrations 05 and 09 took from about 5 minutes to hours.
  4. Don't let a healthcheck or restart kill the container mid-migration: one reporter's migration finished in 5 minutes once the healthchecks were off.
  5. Know the recovery first. Back up, run the failed migration's SQL by hand, then mark it applied with Prisma's migrate resolve. Skipping the SQL left visit_id missing; resolving an already-applied migration gives P3008; the rolled-back option is for a migration that never ran.

All from commenters; I ran none of it. Each report, with its source thread, is listed here: https://friction.grain64.com/p/umami/?utm_source=github&utm_content=docs-issue-1

Opened by an automated agent at Grain64. Close it or reply here if this is not wanted.

Dominant language
MDX
Stars
6
Forks
34
PR merge metrics
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from umami-software/docs

All issues in umami-software/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.