From d4f60b85808ecc95b277d6611a976e5c3ce5f660 Mon Sep 17 00:00:00 2001 From: SchiZzA Date: Sun, 26 Jul 2026 23:42:19 +0200 Subject: [PATCH] fix(document): Explain when delete-and-reinstall preserves entity history --- README.md | 12 ++++++++++++ custom_components/sws12500/predecessor.py | 10 ++++++++++ 2 files changed, 22 insertions(+) diff --git a/README.md b/README.md index 5c70617..a1382b6 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,11 @@ historical data. > That action removes the entity registry records, and your history and long-term statistics have nothing left to attach to once they are gone. > They cannot be relinked afterwards, not even by the new integration. > +> This applies to the rename specifically, not to deleting the integration in general. +> Home Assistant remembers a deleted entity together with the integration it belonged to, and it only ever hands it back to that same integration. +> The new integration is a different one, so nothing of the old entry is handed to it, and there is no way back to the history that was attached to those records. +> Deleting and re-adding *this* integration is the other case, and there it is safe: see [Upgrading from PWS to WSLink](#upgrading-from-pws-to-wslink). +> > Removing the *repository* in HACS is safe and is exactly what the migration expects. > The config entry stays where it is, showing up as `Integration not found`, which looks broken but is the state the new integration needs in order to take your entities over with their history intact. > Do it before you install the new integration: as long as the old version is still on disk it holds the webhook routes, and the new one refuses to start with `Webhook routes are already registered by another instance of this integration`. @@ -293,6 +298,13 @@ measurement scale. - because sensor unique IDs stay the same, you will not lose any of your historical data +Home Assistant remembers deleted entities together with the integration they belonged to. +Removing and re-adding this one is the same integration both times, so every sensor gets its original entity ID back, and the recorded history, the long-term statistics, the area, the aliases and the categories come back with it. +The records are kept for 30 days after the removal, so reinstall within that window. + +That guarantee is tied to it being the same integration, which is why the planned rename to a new integration cannot rely on it and needs a real migration instead. +See [Integration rename is planned for the next major release](#integration-rename-is-planned-for-the-next-major-release) for what not to do when that day comes. + ## Resending data to Windy API - First of all you need to create account at [Windy stations](https://stations.windy.com). diff --git a/custom_components/sws12500/predecessor.py b/custom_components/sws12500/predecessor.py index fbe75cf..9744ced 100644 --- a/custom_components/sws12500/predecessor.py +++ b/custom_components/sws12500/predecessor.py @@ -7,6 +7,16 @@ domain change therefore costs nothing *provided the registry entries are carried rather than recreated*. A recreated entity gets a fresh `entity_id` (or the same one with an `_2` suffix, if the old entry still holds it) and its history is orphaned. +The registry does hand a deleted entity back on recreation, but only within one +integration: deleted entries are held under `(domain, platform, unique_id)`, where +`platform` is the owning integration's domain, and `async_get_or_create` restores the old +`entity_id` only when that whole key matches again and the id is still free. Deleting and +re-adding the *same* integration therefore keeps its history on its own, which is why the +README can tell PWS users to reinstall in place. A domain change never matches the key, so +that path is not even consulted, and this module is what makes the move deterministic +instead. The restore is time limited as well: `ORPHANED_ENTITY_KEEP_SECONDS` drops the +deleted records 30 days after the config entry goes away. + `entity_registry.async_update_entity_platform` is the supported way to carry them over. It rewrites `platform` and `config_entry_id` and leaves `entity_id` alone. Everything the user set by hand rides along for free, because the registry entry itself survives: