Skip to main content

Import Database and Media Dump

This article is structured for an EMS export but may also apply in other circumstances.

For support on Synapse or matrix-media-repo, ask in the Matrix rooms #synapse:matrix.org and #mediarepo:t2bot.io

Important

Do not cancel your EMS server until you have received your export and verified its content. Canceling your server will erase your data.

Prerequisites

You need these items to complete the import. If you are migrating from EMS, EMS support will provide all five to you.

  • Database dump
  • Media export
  • GPG decryption password
  • Pepper
  • Synapse signing key

Import process

  1. Following official documentation, install and configure

    1. PostgreSQL
    2. Synapse - install the same version as your EMS server is running. You can check that at https://yourHostname.ems.host/_matrix/federation/v1/version
    3. matrix-media-repo
  2. When generating your Synapse configuration file, you MUST use the same domain as your EMS server.

  3. Do not start Synapse yet.

  4. In the Synapse config file (usually homeserver.yaml), set:

    1. pepper to the value received. If you do not do this, you have to reset all passwords.
    2. Signing key. This is stored in a file. See this config file option for path. Alternatively, add the old key to old_signing_keys. If your EMS server is still running, you can find your public signing key at https://yourHostname.ems.host/_matrix/key/v2/server
  5. Download the database and media exports provided.

  6. Decrypt and extract the exports

    export emsHostname=yourHostname
    
    gpg --no-symkey-cache --output $emsHostname-database_export.sql.gz \
    	--decrypt $emsHostname-database_export.sql.gz.gpg
    
    gpg --no-symkey-cache --output $emsHostname-media_export.tar.gz \
    	--decrypt $emsHostname-media_export.tar.gz.gpg
    
    gzip --decompress $emsHostname-database_export.sql.gz
    
    tar --gunzip --extract --verbose --file $emsHostname-media_export.tar.gz
    
  7. Import the database dump

    1. If your Synapse database is not empty, empty it
      WARNING - THIS WILL IMMEDIATELY AND IRRECOVERABLY DELETE DATA. WE TAKE NO RESPONSIBILITY IF YOU DELETE THE WRONG DATABASE OR THE WRONG DATA

      Connect to the database with psql, then run the following queries:

      DO $$ DECLARE
      r RECORD;
      BEGIN
          FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = current_schema()) LOOP
              EXECUTE 'DROP TABLE ' || quote_ident(r.tablename) || ' CASCADE';
          END LOOP;
      END $$;
      
      DROP sequence cache_invalidation_stream_seq;
      DROP sequence state_group_id_seq;
      DROP sequence user_id_seq;
      
    2. Disconnect from the database, then import the database dump

      psql --username USERNAME --host HOSTNAME --dbname DATABASE_NAME < $emsHostname-database_export.sql
      
    3. Verify that sequence was set correctly. Connect to the database and run the query

      SELECT * FROM state_group_id_seq;
      

      last_value should be greater than 1

  8. Import media according to documentation here.

  9. Start Synapse.

  10. Optionally, install Element Web or use another Matrix client.