Skip to content

Importing from Umami and Matomo

Bring your history over from a dump of the tool's database: Umami's PostgreSQL database as plain SQL, Matomo's MySQL or MariaDB database with --hex-blob. Either can be gzipped. Import Umami before Matomo.

pg_dump <umami_db> > umami.sql                          # on the Umami server
mysqldump --single-transaction --hex-blob <matomo_db> matomo_site \
  matomo_log_visit matomo_log_link_visit_action matomo_log_action \
  | gzip > matomo.sql.gz                                # on the Matomo server
abilian-analytics import umami umami.sql --owner you@example.com --dry-run
abilian-analytics import umami umami.sql --owner you@example.com
abilian-analytics import matomo matomo.sql.gz --owner you@example.com --dry-run
abilian-analytics import matomo matomo.sql.gz --owner you@example.com

Matomo's tables may be prefixed piwik_ rather than matomo_: its config/config.ini.php says which (tables_prefix), with the database's name and credentials.

A dry run changes nothing: it reports the projects it would create and the visits and events it would import per hostname. It also lists what it would skip. Read it before the real import. On Hop3, the runbook gives the exact commands.

What goes where

  • Each of the tool's websites gets a project, named after it and claiming its domain, owned by the --owner account. To group several websites in one project, create it first with the right patterns (say abilian.com and *.abilian.com): websites whose domain a project already claims get no project of their own. A Matomo website without a main URL gets none either: create a project claiming its hostnames, then import again.
  • Each page view goes to the project claiming its hostname, as live hits do. The report lists the hostnames no project claims (other domains, staging sites, localhost, scanners probing made-up subdomains); their page views are skipped. Add patterns and import again to include some of them.

Each period counted once

On each site, an import stops at the first visit of a source that comes before it: our tracker, then Umami, then Matomo. A period that two tools tracked is counted once.

Importing again replaces the previous import from that tool, and leaves the others as they are.

What is kept

  • The dumps keep neither IP addresses nor user agents. Imported visits are judged on the browser's name (Matomo counts headless Chrome, which is left out here), the country and the referrer, but not on the network.
  • From Matomo, only page views are imported: downloads, outlinks, site searches and Matomo's events are left out. Matomo records one referrer per visit, which goes with the visit's first page.
  • A visit's duration runs from its first page to its last.

Delete the dumps once imported: they hold the tools' raw data, Matomo's with the visitors' IP addresses.