Migrating Home Assistant InfluxDB v1 to VictoriaMetrics
Disclaimer: This write-up was drafted with the assistance of Claude AI (claude.ai) based on a real, verified, and successful migration performed on a live Home Assistant installation. While the process has been tested end-to-end, it is provided as-is without any warranty or guarantee. The authors accept no liability for data loss, system instability, or any other damage resulting from following these instructions. Always back up your data before proceeding. Test in a non-production environment if possible.
Overview
This guide covers migrating historical Home Assistant data from the InfluxDB v1 addon to the VictoriaMetrics addon, using the official vmctl migration tool. VictoriaMetrics offers significantly better compression (typically 5-10x), lower resource usage, and long-term retention support.
Prerequisites
- Home Assistant OS or Supervised installation
- InfluxDB v1 addon installed and containing your historical data
- A PC or laptop on the same local network (Windows, Linux, or macOS)
Step 1 - Back Up Your Data
Before anything else, create a full snapshot. Go to Settings > System > Backups, click Create backup, and download it to a safe location.
Step 2 - Install the VictoriaMetrics Addon
Go to Settings > Add-ons > Add-on Store, click the three-dot menu > Repositories and add:
https://github.com/VictoriaMetrics-Community/homeassistant-addon-victoriametrics
Search for VictoriaMetrics, install it, then start it. Check the Log tab to confirm it is running without errors. By default it listens on port 8428.
Once running, open the VictoriaMetrics UI at http://<ha-ip>:8428/vmui and click the cog icon in the top right corner to set your timezone. This ensures timestamps are displayed correctly in graphs and query results.
Step 3 - Temporarily Disable InfluxDB Authentication
vmctl connects directly to InfluxDB over the network. Even though HA itself connects without credentials via the internal supervisor network, external connections require authentication. The simplest solution is to temporarily disable auth for the duration of the migration.
Go to Settings > Add-ons > InfluxDB > Configuration tab and change auth: true to auth: false. Save and restart the InfluxDB addon. You will re-enable this in Step 7.
Step 4 - Download vmctl
vmctl is the official VictoriaMetrics migration tool. Download the vmutils package for your OS from the VictoriaMetrics releases page. Look for vmutils-windows-amd64-<version>.zip on Windows or vmutils-linux-amd64-<version>.tar.gz on Linux/macOS. Extract the archive — vmctl is included inside.
Step 5 - Run the Migration
Replace <ha-ip> with your Home Assistant’s local IP address.
Windows:
vmctl-windows-amd64-prod.exe influx ^
--influx-addr http://<ha-ip>:8086 ^
--influx-database homeassistant ^
--vm-addr http://<ha-ip>:8428 ^
--influx-concurrency 1
Linux / macOS:
./vmctl-prod influx \
--influx-addr http://<ha-ip>:8086 \
--influx-database homeassistant \
--vm-addr http://<ha-ip>:8428 \
--influx-concurrency 1
--influx-concurrency 1 keeps load low on the HA host. You can raise it to 2 or 3 if migration is slow and your hardware can handle it. The tool displays progress as it works through each measurement. Depending on your data volume this may take anywhere from a few minutes to several hours.
Step 6 - Verify the Migration
Open http://<ha-ip>:8428/vmui and go to the Explore tab. First, set the time range to at least the last 24 hours using the time picker in the top right — if the migration took several hours, a shorter window may show no data even when the migration succeeded.
A good first query is a broad regex search — since most installations have at least one temperature sensor, try:
{entity_id=~".*temp.*"}
This returns all metrics where the entity_id label contains the word “temp”, regardless of metric name. Note that entity_id is stored without the domain prefix, so it will be living_room_temp rather than sensor.living_room_temp.
The query will return several metric types per entity (value, friendly_name, state_class, etc.). To limit results to just the actual measurements, add a __name__ filter:
{entity_id=~".*temp.*", __name__=~".*_value"}
Replace temp with any part of your entity name to find it. Once you can see how your data is stored, you can build more precise queries. Use the Cardinality Explorer in the top menu to browse all available metrics and labels.
Step 7 - Re-enable InfluxDB Authentication
Go to Settings > Add-ons > InfluxDB > Configuration, change auth back to true, save and restart the addon.
Step 8 - Reconfigure the HA InfluxDB Integration
VictoriaMetrics natively accepts the InfluxDB line protocol, so you can keep the existing InfluxDB integration and simply reconfigure it to point at VictoriaMetrics. However, the integration only supports one instance at a time and does not allow editing the host in place — you need to remove the existing integration and add it again with the new connection details.
First, note down your current InfluxDB integration settings (database name, any tags or exclude filters you may have configured) so you can replicate them. Go to Settings > Devices & Services, find the InfluxDB integration, click the three-dot menu and select Delete.
Then add it again using the Add Integration button, search for InfluxDB and enter the new connection parameters:
- Host: the internal Docker hostname of the VictoriaMetrics addon, visible on the addon’s info page in HA (example:
1bd4a9fb-victoria-metrics)
- Port:
8428
- Database:
homeassistant (same name as was used in your InfluxDB configuration)
Leave username and password empty. Re-apply any custom settings you noted down from your previous configuration. Save and confirm that new sensor data starts appearing in VictoriaMetrics.
Step 9 - Remove or Stop the InfluxDB Addon (Optional)
This step is irreversible. Uninstalling the InfluxDB addon will permanently delete all data stored in it. There is no undo.
Only proceed if you are fully satisfied that the migration is complete. Before removing the addon, verify that:
- All your important entities have historical data visible in VictoriaMetrics covering the expected time range
- New data is being written correctly (check a recent timestamp in vmui)
- You have a full HA backup from Step 1 stored safely off-device
If you have any doubt, leave the InfluxDB addon installed and simply stop it. Disk space can be recovered later once you are confident. When you are ready, uninstall the addon from Settings > Add-ons > InfluxDB > Uninstall.
Querying Your Data
VictoriaMetrics uses MetricsQL, which is compatible with PromQL. The metric names in VictoriaMetrics depend on how InfluxDB was configured in HA. The most common setup uses the unit of measurement as the measurement name, resulting in metric names like °C_value or %_value. If the domain was used instead, metric names will look like sensor_value. Use the Cardinality Explorer or the broad regex queries from Step 6 to discover the exact names in your installation.
Note that entity_id is stored without the domain prefix — use living_room_temp rather than sensor.living_room_temp.
Show all value readings for a specific entity:
{entity_id="living_room_temp", __name__=~".*_value"}
Hourly average for a sensor:
avg_over_time({entity_id="living_room_temp", __name__=~".*_value"}[1h])
List all entity IDs that have value metrics:
group by (entity_id) ({__name__=~".*_value"})
Binary sensor history:
{entity_id="front_door", __name__=~".*_value"}
Troubleshooting
vmctl reports “unable to parse authentication credentials” — go back to Step 3 and confirm auth is set to false in the InfluxDB addon configuration.
vmctl completes instantly with 0 metrics migrated — double-check that --influx-database matches the database name exactly (default is homeassistant).
No data appears in vmui after migration — confirm the --vm-addr port is 8428 and extend the time range in the vmui time picker to cover the period before the migration ran.
HA is not writing new data after reconfiguration — verify the Docker hostname in the integration config matches what is shown on the addon info page, and confirm the port is 8428.
