Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add documentation for sync agents #2434

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add documentation for sync agents #2434

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51946a7
Add documentation for sync agents
ludeeus Oct 31, 2024
781eb9b
Update backup.md
ludeeus Oct 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions blog/2025-12-31-backup-sync-agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
35 changes: 34 additions & 1 deletion docs/core/platform/backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
ludeeus marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Fix grammar and enhance method descriptions.

The method descriptions section needs grammatical fixes and could benefit from more detailed information:

-The base class `BackupSyncAgent` has several methods that can needs to be implemented.
+The base class `BackupSyncAgent` has several methods that need to be implemented.

Consider adding return type information and error handling expectations for each method in the table.

Here's a suggested enhancement for the method table:

Method Description Return Type Error Handling
async_download_backup Downloads a backup from the remote location using the provided ID. None Should raise BackupError on failure
async_upload_backup Uploads a backup file with associated metadata to the remote location. str (backup ID) Should raise BackupError on failure
async_list_backups Retrieves a list of available backups from the remote location. list[BackupInfo] Should raise BackupError on connection issues
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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.
The base class `BackupSyncAgent` has several methods that need 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.
🧰 Tools
🪛 LanguageTool

[uncategorized] ~55-~55: Possible missing preposition found.
Context: ... be synced. async_list_backups | List backups. When a user creates a backup, Home As...

(AI_HYDRA_LEO_MISSING_OF)


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.