diff options
author | Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> | 2021-06-03 14:06:03 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-06-03 14:06:03 +0100 |
commit | 73636cab69c32746ef6b7708deeeb0c718b7b3b9 (patch) | |
tree | 9d4354f02e85218e82ea3e4d7fe3acc17869c02b /docs/admin_api/purge_history_api.md | |
parent | r0.6.1 support: /rooms/:roomId/aliases endpoint (#9224) (diff) | |
download | synapse-73636cab69c32746ef6b7708deeeb0c718b7b3b9.tar.xz |
Convert admin api docs to markdown (#10089)
So that they render nicely in mdbook (see #10086), and so that we no longer have a mix of structured text languages in our documentation (excluding files outside of `docs/`).
Diffstat (limited to 'docs/admin_api/purge_history_api.md')
-rw-r--r-- | docs/admin_api/purge_history_api.md | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/docs/admin_api/purge_history_api.md b/docs/admin_api/purge_history_api.md new file mode 100644 index 0000000000..44971acd91 --- /dev/null +++ b/docs/admin_api/purge_history_api.md @@ -0,0 +1,78 @@ +# Purge History API + +The purge history API allows server admins to purge historic events from their +database, reclaiming disk space. + +Depending on the amount of history being purged a call to the API may take +several minutes or longer. During this period users will not be able to +paginate further back in the room from the point being purged from. + +Note that Synapse requires at least one message in each room, so it will never +delete the last message in a room. + +The API is: + +``` +POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>] +``` + +To use it, you will need to authenticate by providing an `access_token` for a +server admin: [Admin API](README.rst) + +By default, events sent by local users are not deleted, as they may represent +the only copies of this content in existence. (Events sent by remote users are +deleted.) + +Room state data (such as joins, leaves, topic) is always preserved. + +To delete local message events as well, set `delete_local_events` in the body: + +``` +{ + "delete_local_events": true +} +``` + +The caller must specify the point in the room to purge up to. This can be +specified by including an event_id in the URI, or by setting a +`purge_up_to_event_id` or `purge_up_to_ts` in the request body. If an event +id is given, that event (and others at the same graph depth) will be retained. +If `purge_up_to_ts` is given, it should be a timestamp since the unix epoch, +in milliseconds. + +The API starts the purge running, and returns immediately with a JSON body with +a purge id: + +```json +{ + "purge_id": "<opaque id>" +} +``` + +## Purge status query + +It is possible to poll for updates on recent purges with a second API; + +``` +GET /_synapse/admin/v1/purge_history_status/<purge_id> +``` + +Again, you will need to authenticate by providing an `access_token` for a +server admin. + +This API returns a JSON body like the following: + +```json +{ + "status": "active" +} +``` + +The status will be one of `active`, `complete`, or `failed`. + +## Reclaim disk space (Postgres) + +To reclaim the disk space and return it to the operating system, you need to run +`VACUUM FULL;` on the database. + +<https://www.postgresql.org/docs/current/sql-vacuum.html> |