How to Back Up and Restore a Matrix Synapse PostgreSQL Database

A dependable Synapse recovery starts with a PostgreSQL dump that can be read, a clean destination database, and the matching homeserver files. For a typical single-database installation, Synapse’s own backup guide recommends PostgreSQL’s custom dump format and excludes the contents of e2e_one_time_keys_json. Restore into a newly created, empty database; do not layer a dump over tables left by an earlier install. Then confirm Synapse starts against the restored database and that local media and signing keys are present.

This walkthrough assumes a Linux host, a PostgreSQL database named synapse, and a database role named synapse_user. Substitute the database, role, backup path, service name, and configuration paths used by your deployment. Docker Compose, Kubernetes, managed PostgreSQL, and multi-database Synapse deployments need equivalent commands for their environment.

What a database dump does—and does not—protect

pg_dump captures one PostgreSQL database in a consistent snapshot, so PostgreSQL and Synapse can remain online while the dump runs. A custom-format archive (-Fc) can be inspected and restored with pg_restore. The Synapse guide specifically recommends excluding one-time-key table data: restoring older used keys may cause clients to receive keys again and can lead to message decryption errors. The table definition can still appear in the archive; when checking the archive list, look for table-data entries rather than assuming a listed table contains rows.

A database dump alone is not a complete homeserver backup. Also retain homeserver.yaml and any files it references, the server signing key, and the media store directory. Synapse’s backup guide identifies locally uploaded media as important because the homeserver may hold the only copy. If your configuration uses more than one database entry, plan a dump for every database Synapse uses.

Before you begin

• Confirm the configured database name, user, host, port, and whether Synapse uses one database or several.
• Check that PostgreSQL client utilities pg_dump, pg_restore, createdb, and psql are installed and compatible with your PostgreSQL server.
• Choose a protected backup destination with enough free space. Dumps can contain private messages and account data; restrict access and encrypt backups at rest and in transit.
• Record the Synapse configuration directory, signing-key path, and media_store_path. Back up secrets without exposing them in shell history, chat, or logs.
• Decide how you will test recovery. A test restore on an isolated host or staging database is stronger evidence than a successful dump command alone.

Create and check the PostgreSQL backup

1. Confirm the target database and role

On a self-managed PostgreSQL host, connect as a PostgreSQL administrator and inspect the database list and relations. Do not rely on an assumed name copied from a sample configuration. If your homeserver uses a remote or managed database, use its approved connection method and verify that the dump account has the required read access.

2. Make a custom-format dump

Create a directory that only the backup account or administrators can read. The example below runs pg_dump as the local PostgreSQL operating-system account and writes to a protected path. Change the path to one that exists and is writable in your setup.

sudo -u postgres pg_dump -Fc \
  --exclude-table-data e2e_one_time_keys_json \
  synapse -f /var/backups/synapse/synapse.dump

If your database is remote, supply connection settings with the method approved in your environment, such as a protected .pgpass file or libpq environment variables. Avoid putting a password directly in the command line. Keep the exclusion option unless you have a deliberate, documented reason to handle the one-time-key table differently.

3. Check the archive and preserve a checksum

Confirm the dump file exists, is nonzero, and is readable as a PostgreSQL archive. A successful listing is a useful first check, but it does not prove that a restore will finish or that the full homeserver can serve users.

sudo -u postgres pg_restore --list /var/backups/synapse/synapse.dump
sha256sum /var/backups/synapse/synapse.dump

Store the checksum beside the backup record, then copy the dump to a separate system or backup service. Recalculate the checksum after copying and compare the values. For production recovery objectives, schedule regular backups, retain multiple generations, encrypt them, and run periodic restore drills.

Restore into a clean database

4. Stop Synapse and prepare an empty destination

For a restore, stop Synapse first so it cannot reconnect while the database is being replaced or tested. The service name below is common on some package installations, but it varies; Docker users should stop the Synapse service through their Compose project, and orchestrated deployments should use their normal maintenance procedure. PostgreSQL itself does not need to be stopped.

Use a new, empty database for the restore. Do not restore over an existing Synapse database or one that already contains tables. If you need to preserve the current database for rollback, leave it intact and restore under a temporary database name, then validate before changing Synapse configuration.

sudo -u postgres createdb \
  --encoding=UTF8 --locale=C --template=template0 \
  --owner=synapse_user synapse

Właściciel bazy danych i ustawienia regionalne powinny być zgodne z wymaganiami konfiguracji Synapse. Jeśli nazwa docelowa już istnieje, zatrzymaj się i potwierdź, której bazy danych zamierzasz użyć; nie zakładaj, że jej usunięcie jest bezpieczne. Najpierw utwórz wszystkie wymagane role PostgreSQL. Pojedyncza baza danych pg_dumpnie obejmuje ról obejmujących cały klaster, więc administrator przechodzący do nowego klastra PostgreSQL może również potrzebować oddzielnej, chronionej kopii zapasowej globalnych danych utworzonej za pomocą pg_dumpall --globals-only.

5. Przywróć archiwum i obsługuj klucze jednorazowe

Załaduj archiwum niestandardowe do tego pustego miejsca docelowego. Opcja jawnego błędu powoduje, że przywracanie zatrzymuje się po napotkaniu błędu, zamiast kontynuować i pozostawić niekompletny wynik, który łatwo przeoczyć.

sudo -u postgres pg_restore --exit-on-error \
  --dbname=synapse /var/backups/synapse/synapse.dump

Jeśli zrzut nie wykluczył e2e_one_time_keys_json, połącz się z przywróconą bazą danych i usuń tę tabelę przed uruchomieniem Synapse. Jest to udokumentowane przez Synapse zabezpieczenie odzyskiwania dla kopii zapasowych zawierających te wiersze. Nie uruchamiaj tego polecenia w aktywnej bazie danych przypadkowo: usunie ono wszystkie wiersze z tej tabeli.

sudo -u postgres psql -d synapse \
  -c 'TRUNCATE e2e_one_time_keys_json;'

Jeśli użyto zalecanego wykluczenia, przywrócenie nie zawiera starych wierszy klucza jednorazowego, a ten krok obcinania jest zbędny. Wpis tabeli w pg_restore --listmoże reprezentować definicję tabeli bez jej danych. Sprawdź TABLE DATAwpisy podczas przeglądania zawartości archiwum; najbezpieczniejszym rekordem operacyjnym jest dokładnie to samo polecenie zrzutu (dump).

Przywróć Synapse i sprawdź odzyskiwanie

6. Przywróć pliki towarzyszące i uruchom Synapse

Przed ponownym uruchomieniem upewnij się, że przywrócona konfiguracja wskazuje na docelową bazę danych, a oczekiwany klucz podpisu i magazyn nośników są dostępne dla procesu Synapse. Jeśli przywróciłeś bazę danych pod tymczasową nazwą, zaktualizuj ustawienia bazy danych w bezpieczny sposób, zweryfikuj plik i użyj standardowego procesu wdrażania, aby je aktywować. Zachowaj starą bazę danych i poprzednią konfigurację, dopóki nowa instancja nie przejdzie pomyślnie kontroli.

Uruchom usługę za pomocą polecenia odpowiedniego dla wdrożenia. Na hoście systemd sprawdź status usługi i ostatnie logi. W kontenerach sprawdź stan kontenera i logi. Uruchomiony proces to początkowy sygnał, a nie dowód, że użytkownicy mogą odczytywać pokoje, wysyłać wiadomości lub pobierać załączniki.

7. Funkcje testowe, od których zależą użytkownicy

• Upewnij się, że Synapse uruchamia się bez migracji bazy danych, uprawnień, ustawień regionalnych lub błędów połączenia.
• Zaloguj się na konto testowe i przeczytaj istniejące pokoje. Wyślij wiadomość testową, jeśli Twój plan konserwacji na to pozwala.
• Sprawdź zachowanie federacji i usługi aplikacji, jeśli te funkcje są częścią wdrożenia.
• Otwórz znany lokalnie przesłany załącznik lub awatar, aby sprawdzić, czy magazyn multimediów jest zgodny z przywróconą bazą danych.
• Sprawdź logi Synapse i PostgreSQL pod kątem powtarzających się błędów po uruchomieniu, a nie tylko po pierwszej pomyślnej kontroli stanu.

Przywracanie może być technicznie skuteczne, nawet jeśli brakuje plików multimedialnych, konfiguracji, do której się odwołuje, lub ról. Jeśli użytkownicy widzą brakujące załączniki, należy zweryfikować skonfigurowany magazyn multimediów i przywrócić odpowiednią lokalną kopię zapasową multimediów. Jeśli Synapse nie może nawiązać połączenia, należy porównać właściciela przywróconej bazy danych, dane uwierzytelniające, hosta, nazwę bazy danych, ustawienia regionalne i aktywny plik konfiguracyjny.

Typowe sygnały awarii i kiedy należy zmienić metodę

Zrzuty logiczne są przenośne i proste w obsłudze w przypadku wielu małych i średnich wdrożeń, ale ich przywrócenie wraz z rozwojem bazy danych może zająć trochę czasu. W przypadku usługi dużej lub o wysokiej dostępności należy zapoznać się z aktualną dokumentacją dotyczącą tworzenia kopii zapasowych PostgreSQL i zaplanować przetestowaną kopię fizyczną lub projekt odzyskiwania danych z określonego punktu w czasie. Należy zachować niezależny zrzut logiczny, jeśli służy on oddzielnej przenośności lub potrzebie audytu. Żadna z tych metod nie chroni plików przechowywanych poza bazą danych PostgreSQL, chyba że są one osobno archiwizowane.

Lista kontrolna odzyskiwania

• Zrzut można odczytać za pomocą programu pg_restore --list, a jego suma kontrolna zgadza się z kopią znajdującą się poza hostem.
• Przywrócenie nastąpiło do nowej, pustej bazy danych z oczekiwanym kodowaniem, ustawieniami regionalnymi, właścicielem i rolami.
• Wykluczono wiersze z kluczami jednorazowymi lub tabela została obcięta przed ponownym uruchomieniem programu Synapse.
• Pliki konfiguracyjne, klucz podpisu i wymagane nośniki lokalne zostały przywrócone z kompatybilnych kopii zapasowych.
• Logi Synapse są wystarczająco czyste, aby umożliwić korzystanie z usługi, a kontrole na poziomie klienta dotyczące pokoi i multimediów przebiegają pomyślnie.
• Ćwiczenia przywracania danych potwierdziły udokumentowane kroki odzyskiwania i zmierzyły rzeczywisty czas przywracania.

Oficjalne referencje

• Przewodnik po tworzeniu kopii zapasowych Synapse — porady dotyczące konkretnych baz danych, obsługa kluczy jednorazowych, konfiguracja, klucze podpisywania i magazyn multimediów.
• Synapse: Korzystanie z PostgreSQL — szczegóły instalacji i konfiguracji bazy danych.
• PostgreSQL: pg_dump , pg_restore oraz tworzenie kopii zapasowych i przywracanie danych w ramach PostgreSQL — opcje archiwizacji i szersze strategie tworzenia kopii zapasowych.

Dokumentacja sprawdzona 6 października 2026 r. Nazwy poleceń i zarządzanie usługami różnią się w zależności od systemu operacyjnego, obrazu kontenera, wersji PostgreSQL i wdrożenia Synapse. Sprawdź zgodność instrukcji z dokumentacją dla uruchamianych wersji i metod pakowania.