umami
FeaturesDocsCommunityPricing
16.8k
Get started

Migrating v1 to v2

Umami v2 introduces a redesigned schema and a number of breaking changes.

Breaking changes

  • The API endpoints have changed including new ones being added. See API for more information.
  • The tracker script has been renamed from umami.js to script.js.
  • The collect api endpoint has been renamed from /api/collect to /api/send.
  • The tracker no longer uses CSS class names to trigger events. It now uses HTML data attributes. See Track events for more information.
  • The methods on the global umami JavaScript object have changed. There is now a single .track() method and a new way to send event data. See Tracker functions for more information.
  • The TRACKER_SCRIPT_NAME environment variable no longer appends the .js extension to the script name. See Environment variables for more information.

Data migration

Due to the schema changes, your data in your v1 database needs to be converted into v2. To assist with the migration we created a script @umami/migrate-v1-v2 that will migrate all of your data for you.

Requirements

  • Database schema must be in sync with the latest v1 version (v1.4.0). The script will query the prisma migrations table to ensure the latest migrations have been ran.

Important

  • Backup your target database prior to use. Potential data loss may occur if the migration is interrupted.
  • For users with larger datasets (5M+), the migration may take while. Please plan accordingly.
  • The script will NOT migrate any event data into v2.
  • The script will ask you if you want to drop your v1 tables after the migration is complete.
  • If an event_data table is found populated with data, it will be renamed to v1_event_data but not dropped.

Troubleshooting

  • If your DATABASE_URL is localhost and the migration can't connect to the database, try changing to an IP address, for example: 127.0.0.1.

Running migration

There are two ways to run the migration script.

1. Running inside the Umami folder

Use this method if you have terminal access to your application folder. Make sure your application is already built. If not run yarn build first.

cd umami
npx @umami/migrate-v1-v2@latest

2. Running standalone

Use this method if you don't have access to your application folder like when deployed to Vercel or Netlify.

Install

git clone https://github.com/umami-software/migrate-v1-v2.git
cd migrate-v1-v2
yarn install
yarn build

Configure

Create an .env file with the following variable defined:

DATABASE_URL={connection url}

Run

yarn start

Docker migration

Go into your running Docker container. You can find the name by the output of docker ps.

docker exec -ti -u 0 <app container name> sh

Run the migration script.

npx @umami/migrate-v1-v2@latest

When the migration is run successfully, it should look like this: