mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-10 02:46:29 +00:00
Add documentation for sync agents
This commit is contained in:
parent
ab02bc1e01
commit
51946a7082
13
blog/2025-12-31-backup-sync-agents.md
Normal file
13
blog/2025-12-31-backup-sync-agents.md
Normal file
@ -0,0 +1,13 @@
|
||||
---
|
||||
author: Joakim Sørensen
|
||||
authorURL: https://github.com/ludeeus
|
||||
authorImageURL: /img/profile/ludeeus.jpg
|
||||
authorTwitter: ludeeus
|
||||
title: "Backup sync agents"
|
||||
---
|
||||
|
||||
As of Home Assistant Core 2025.12, integrations can provide [sync agents](/docs/core/platform/backup#sync-agents) to allow users to back up and restore their data to and from external services.
|
||||
|
||||
Sync agents allows integrations to store backups in a remote location, such as a cloud service or a network-attached storage (NAS) device.
|
||||
|
||||
More details can be found in the [backup platform documentation](/docs/core/platform/backup#sync-agents).
|
@ -2,11 +2,15 @@
|
||||
title: "Backup"
|
||||
---
|
||||
|
||||
The backup platform consists of two parts; [Pre/Post backup hooks](#prepost-backup-hooks) and [Sync agents](#sync-agents).
|
||||
|
||||
## Pre/Post backup hooks
|
||||
|
||||
When Home Assistant is creating a backup, there might be a need to pause certain operations in the integration, or dumping data so it can properly be restored.
|
||||
|
||||
This is done by adding 2 functions (`async_pre_backup` and `async_post_backup`) to `backup.py`
|
||||
|
||||
## Adding support
|
||||
### Adding support
|
||||
|
||||
The quickest way to add backup support to a new integration is by using our built-in scaffold template. From a Home Assistant dev environment, run `python3 -m script.scaffold backup` and follow the instructions.
|
||||
|
||||
@ -22,3 +26,32 @@ async def async_pre_backup(hass: HomeAssistant) -> None:
|
||||
async def async_post_backup(hass: HomeAssistant) -> None:
|
||||
"""Perform operations after a backup finishes."""
|
||||
```
|
||||
|
||||
## Sync agents
|
||||
|
||||
Sync agents are used to dispatch a backup to a remote location. This is done by implementing the a `BackupSyncAgent` class.
|
||||
|
||||
To register your sync agent, you need to add a `async_get_backup_sync_agents` function to your integrations backup platform.
|
||||
|
||||
```python
|
||||
async def async_get_backup_sync_agents(
|
||||
hass: HomeAssistant,
|
||||
) -> list[BackupSyncAgent]:
|
||||
"""Register the backup sync agents."""
|
||||
return [LoremIpsumBackupSyncAgent("syncer")]
|
||||
|
||||
class LoremIpsumBackupSyncAgent(BackupSyncAgent):
|
||||
...
|
||||
```
|
||||
|
||||
### Sync agent methods
|
||||
|
||||
The base class `BackupSyncAgent` has several methods that can needs to be implemented.
|
||||
|
||||
Method | Description
|
||||
:--- | :---
|
||||
`async_download_backup` | Download a backup from the remote location. The `id` parameter is the ID of the synced backup that was returned in `async_list_backups`. The `path` parameter is the full file path to download the synced backup to.
|
||||
`async_upload_backup` | Upload a backup. The `path` parameter is the full file path to the backup that should be synced. The `metadata` parameter contains metadata about the backup that should be synced.
|
||||
`async_list_backups` | List backups.
|
||||
|
||||
When a user creates a backup, Home Assistant will call the `async_upload_backup` method on the sync agent to store the backup in the remote location.
|
||||
|
Loading…
x
Reference in New Issue
Block a user