Docs idea: a "before you upgrade" checklist built from seven umami migration-failure threads
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
- Look for a half-applied migration: check _prisma_migrations for one that started but never finished; it blocks every later migration.
- 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.
- Check the size of the website events table: migrations 05 and 09 took from about 5 minutes to hours.
- 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.
- 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from umami-software/docs
-
Difficulty 1/5 Under an hour Newbie friendliness 84/100
umami-software/docs#47 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
umami-software/docs#33 · 2 comments ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
umami-software/docs#31 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
umami-software/docs#15 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 35/100
umami-software/docs#21 ·
All issues in umami-software/docs
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
Maintainers usually reply within 5 days
-
documentation
Difficulty 1/5 Under an hour Newbie friendliness 82/100
PaloAltoNetworks/pan.dev#1604 ·
Maintainers usually reply within 4 days
-
Difficulty 1/5 Under an hour Newbie friendliness 65/100
Southampton-RSG-Training/ai-fundamentals-for-researchers#28 ·
-
content 📄 needs triage 🤔
Difficulty 1/5 Under an hour Newbie friendliness 82/100
Qiskit/documentation#6033 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
openwatersio/slackwater#550 ·
Maintainers usually reply within 1 day