From 2a8d7b5b9155e8ddc2075a287b558a267aa0c459 Mon Sep 17 00:00:00 2001 From: dgtal1 <27864579+dgtal1@users.noreply.github.com> Date: Fri, 16 Oct 2020 10:31:20 +0200 Subject: [PATCH] Added description on how to migrate a Config Entry to a new version (#640) Co-authored-by: Paulus Schoutsen --- docs/config_entries_config_flow_handler.md | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md index 33506137..d63dfc83 100644 --- a/docs/config_entries_config_flow_handler.md +++ b/docs/config_entries_config_flow_handler.md @@ -159,3 +159,29 @@ Translations for the config flow handlers are defined under the `config` key in ``` When the translations are merged into Home Assistant, they will be automatically uploaded to [Lokalise](https://lokalise.co/) where the translation team will help to translate them in other languages. While developing locally, you will need to run `python3 -m script.translations develop` to see changes made to `strings.json` [More info on translating Home Assistant.](translations.md) + +## Config Entry Migration + +As mentioned above - each Config Entry has a version assigned to it. This is to be able to migrate Config Entry data to new formats when Config Entry schema changes. + +Migration can be handled programatically by implementing function `async_migrate_entry` in your component's `__init__.py` file. The function should return `True` if migration is successfull. + +```python +# Example migration function +async def async_migrate_entry(hass, config_entry: ConfigEntry): + """Migrate old entry.""" + _LOGGER.debug("Migrating from version %s", config_entry.version) + + if config_entry.version == 1: + + new = {**config_entry.data} + # TODO: modify Config Entry data + + config_entry.data = {**new} + + config_entry.version = 2 + + _LOGGER.info("Migration to version %s successful", config_entry.version) + + return True +```