Migrating from Matomo to Databuddy starts with an inventory of what your Matomo installation measures. Reports, custom dimensions, goals, ecommerce tracking, tag-manager configuration, and historical data are separate migration decisions. Replacing a JavaScript snippet does not transfer them automatically.
This walkthrough preserves old reports separately and verifies new collection in Databuddy. It does not import a Matomo database, historical visitor logs, or aggregated reports into Databuddy. Confirm any historical-import requirement before committing to a replacement.
Inventory the installation you actually run
Record whether you use Matomo Cloud or an installation your team operates, the site ID and domain, reporting timezone, tracking method, and reports required by each stakeholder. Check both application code and Matomo Tag Manager. A tracker can be installed through more than one path.
Build a worksheet for the features in use:
| Existing feature | Migration decision | Acceptance check |
|---|---|---|
| Pageviews and virtual navigation | Install the new tracker once | Expected views appear on hard load and client navigation |
| Event category, action, and name | Define a destination event naming scheme | Properties retain the meaning needed for reports |
| Goals or ecommerce outcomes | Identify the authoritative application outcome | Failed and repeated operations do not inflate success |
| Custom dimensions | Keep only necessary supported properties | Values are useful and avoid unnecessary personal data |
| Historical reports | Export and retain independently | Date coverage and required dimensions are readable |
| Tag-manager triggers | Review every trigger and destination | The replacement does not leave duplicate trackers |
Check destination capabilities individually. A product supporting custom events does not establish parity with every Matomo report, plugin, ecommerce feature, or access-control workflow. Keep any essential capability that has no verified replacement in your acceptance criteria.
Export reports before changing access
Matomo documents report exports in formats including CSV and JSON. Choose the reporting period, report, format, row limit, and flattening options that fit your archive. Its Reporting API provides programmatic access to reports; a report export is different from a complete database backup. Use the official Matomo export instructions and Analytics API guide for your installation.
For an installation you operate, preserve any database or configuration backups through your existing tested operations process. A database backup is useful for restoring that installation; it is not a Databuddy import file. Follow your organization's retention and access policies instead of copying all records into a shared migration folder.
Save an export manifest with the source site, timezone, date range, filters, selected dimensions, row limits, and format. Open the files and check required reports before removing account access or decommissioning infrastructure. Preserve the configuration needed to interpret them, especially goal and dimension definitions.
Map Matomo events to explicit destination events
A Matomo event can carry category, action, name, and value. Decide which meaning should become the Databuddy event name and which fields, if any, should become properties. Do not mechanically collapse every combination into an unexplained string.
For example, an application might translate its documented account-creation outcome into a stable event named signup_completed, with a non-sensitive plan property. The mapping should describe a confirmed application outcome. A click on a submit button represents a different point in the journey.
Use the Databuddy browser helpers or server SDK for the chosen source. Review payloads before sending them. Avoid raw form data, authentication tokens, full payment details, and unnecessary identifiers. Archive data should remain an archive; replaying historical rows as current events would change their meaning and can contaminate current reports.
Install and test on a known journey
Follow Databuddy's setup instructions for the destination website and your framework. Keep only one Databuddy installation across application code, plugins, and tag managers. Review enabled collection features and privacy behavior for the configuration you intend to deploy.
Start with synthetic data and a short acceptance journey:
- Open a landing page with a known campaign parameter and inspect the first view.
- Navigate to another page, including a client-side route if your app has one.
- Complete a successful test operation and inspect its event and allowed properties.
- Trigger a failed operation and check that it does not count as success.
- Repeat a callback or retry and inspect duplicates and recovery behavior.
Check the destination reports after the request is sent. A local network capture can show the payload and collector response, but it does not prove hosted report visibility. The Next.js example provides a runnable synthetic journey with explicit failure recovery if you need a development reference.
Reconcile definitions rather than forcing identical totals
Compare a documented time range in the same timezone, with known filters and matching event definitions. Record differences in visitor identity, session rules, bot filtering, collection settings, and report timing before treating unequal totals as dropped events.
Separate what the application attempted, what the browser or server sent, what a collector accepted, and what a report displayed. Investigate a missing step at the boundary where it disappears. Recreating an old dashboard label without its underlying definition can hide a migration error.
Cut over without losing the recovery path
Record the cutover time and deployment revision. Disable the Matomo tracker in the intended environment, including tag-manager triggers, and deploy. Verify that a fresh test journey sends requests to the intended destination and no longer calls the old collector.
Keep a reversible configuration change and retain the archive and reporting definitions. If an essential report or delivery path fails, restore the known collection configuration while you investigate. Decommission an operated Matomo installation only after the replacement workflow and your retention obligations have been checked.
See Plausible, Matomo, and Databuddy compared for selection tradeoffs, or the Plausible migration guide for its different export workflow.