2016-07-28 16:56:09 +03:00
|
|
|
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.
|
|
|
|
|
2020-02-12 18:39:40 +03:00
|
|
|
Note that Synapse requires at least one message in each room, so it will never
|
|
|
|
delete the last message in a room.
|
2020-02-11 20:56:04 +03:00
|
|
|
|
2018-03-02 02:20:54 +03:00
|
|
|
The API is:
|
2016-07-28 16:56:09 +03:00
|
|
|
|
2019-05-01 17:18:58 +03:00
|
|
|
``POST /_synapse/admin/v1/purge_history/<room_id>[/<event_id>]``
|
2016-07-28 16:56:09 +03:00
|
|
|
|
|
|
|
including an ``access_token`` of a server admin.
|
2018-02-08 21:44:52 +03:00
|
|
|
|
|
|
|
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
|
2018-03-15 14:05:42 +03:00
|
|
|
deleted.)
|
2018-02-08 21:44:52 +03:00
|
|
|
|
2018-03-15 14:05:42 +03:00
|
|
|
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:
|
2018-02-08 21:44:52 +03:00
|
|
|
|
|
|
|
.. code:: json
|
|
|
|
|
|
|
|
{
|
2018-02-13 16:04:41 +03:00
|
|
|
"delete_local_events": true
|
2018-02-08 21:44:52 +03:00
|
|
|
}
|
2018-03-02 02:20:54 +03:00
|
|
|
|
|
|
|
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.
|
2018-03-08 14:47:28 +03:00
|
|
|
|
|
|
|
The API starts the purge running, and returns immediately with a JSON body with
|
|
|
|
a purge id:
|
|
|
|
|
|
|
|
.. code:: json
|
|
|
|
|
|
|
|
{
|
|
|
|
"purge_id": "<opaque id>"
|
|
|
|
}
|
|
|
|
|
|
|
|
Purge status query
|
|
|
|
------------------
|
|
|
|
|
|
|
|
It is possible to poll for updates on recent purges with a second API;
|
|
|
|
|
2019-05-01 17:18:58 +03:00
|
|
|
``GET /_synapse/admin/v1/purge_history_status/<purge_id>``
|
2018-03-08 14:47:28 +03:00
|
|
|
|
|
|
|
(again, with a suitable ``access_token``). This API returns a JSON body like
|
|
|
|
the following:
|
|
|
|
|
|
|
|
.. code:: json
|
|
|
|
|
|
|
|
{
|
|
|
|
"status": "active"
|
|
|
|
}
|
|
|
|
|
|
|
|
The status will be one of ``active``, ``complete``, or ``failed``.
|
2018-11-18 21:37:56 +03:00
|
|
|
|
|
|
|
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
|