Upgrade umami v1 to v2

I am using a self-hosted analytics tool called umami. It is easy to understand, unlike Google Analytics which needs a degree to get the basics and it's on my server. So no headaches regarding GDPR and stuff.

I am running this with docker compose and sometimes the upgrade process is, let's say, a bit tricky. Therefore I waited for the big v2.x update.

Today I figured let's see what this v2.x is all about. Checking Github Issues and Discussions I saw nothing problematic, so let's do it.

I also found some docs regarding the migration from v1 to v2:

Migrating v1 to v2 | umami

umami

Upgrading umami

I am currently running these tags:

• ghcr.io/umami-software/umami:postgresql-v1.40.0
• postgres:12.14-alpine

First I checked which version of PostgreSQL is supported and I am in luck, v12.14 is the minium version. Found that

Installation | umami

umami

Create a backup

First things first: Always create a backup!

docker exec -it blog_umami-db_1 pg_dumpall -U umami > umami-All.dump

Migration

The migration needs to be run in the OLD version of the container. So in my case v1.40.0 which already was running. I found that weird, but here we go:

docker exec -it -u 0 blog_umami_1 sh

npx @umami/migrate-v1-v2@latest

Migration output:

Need to install the following packages:
  @umami/migrate-v1-v2@0.15.0
Ok to proceed? (y) y
Running v0.15.0
✓ DATABASE_URL is defined.
✓ Database connection successful.
Preparing v1 tables for migration
✓ Dropped v1 database keys.
✓ Dropped v1 database indexes.
✓ Renamed v1 database tables.
✓ Database v1 tables ready for migration.
Database v2 tables not found.
Adding v2 tables...
✓ Ran sql file /db/postgresql/migrations/01_init/migration.sql.
Prisma schema loaded from prisma/schema.prisma
Datasource "db": PostgreSQL database "umami", schema "public" at "umami-db"
Migration 01_init marked as applied.

✓ Database is ready for migration.
✓ Starting v2 data migration. Please do no cancel this process, it may take a while.
✓ Ran sql file /db/postgresql/data-migration-v2.sql.
✓ Data migration from V1 to V2 tables completed.
✔ Do you want to delete V1 database tables? (Y/N) … Y
✓ Dropped v1 database tables.
✓ Migration successfully completed.
npm notice
npm notice New major version of npm available! 8.19.3 -> 9.8.1
npm notice Changelog: https://github.com/npm/cli/releases/tag/v9.8.1
npm notice Run npm install -g npm@9.8.1 to update!
npm notice

Updating

After the migration was successful I just had to update my docker image tag to the latest stable one: postgresql-v2.5.0

That was it!

Updating postgres

My current PostgreSQL container was running with the tag postgres:12.14-alpine. So I updated to the latest patch release of the version 12 which is 12.16 as of writing this.

Then I tried to update the container to the version 13.12 but that did not work. The container kept restarting. After some Google Foo, I discovered that PostgreSQL will not do the migration for you. It will actually refuse to start when there is an older database version in the database location.

You actually need to create a database dump. Start a fresh and empty PostgreSQL container and then import that dump into the new instance.

Personally, I would prefer to do the migration at startup, but hey, you can not get it all. I know it could be possible with pg_upgrade.

Here are some more info regarding this:

• version policy
• Upgrading PostgreSQL documentation

Since I am still in the minimum requirement for umami I will do this another time. Too lazy right now. 😉