Installing

On Debian with the prosody repository the migrator can be installed by running

sudo apt install prosody-migrator

On other distributions it may be included in the same package as Prosody.

If so you can proceed to Configuration, otherwise see the next section for how to build.

Building

The term “building” is a bit out of place here as the migrator is a collection of Lua scripts that do not need compiling. You can either run it from a Prosody source package or repository checkout - or hopefully the packages you use for your system install it.

If using from the repository, simply cd tools/migration, edit the migrator.cfg.lua in that directory (as described below) and run lua prosody-migrator.lua.

If you want to install the migrator system-wide then you can run make install here, and it will install to the same prefix as Prosody as “prosody-migrator”.

Configuration

The first step for using the migrator is to tell it about the data stores you have. The default config defines two… the file-based one and an SQLite based one.

First, open up /etc/prosody/migrator.cfg.lua in your editor. You should see two stores defined, one called ‘input’ and one called ‘output’. It’s possible to name them what you like, but when running the migrator without config options ‘input’ and ‘output’ are used as the default, er… input and output.

prosody_files {
  hosts = {
    -- each VirtualHost to be migrated must be represented
    ["example.com"] = {
      -- a list of the stores to migrate
      "accounts";
      "roster";
      "archive-archive";
      "pep-pubsub";
      -- etc
    };
  };

  type = "internal"; -- the default file based backend
  path = "/var/lib/prosody";
}

database {
  -- The migration target does not need 'hosts'
  type = "sql";
  driver = "PostgreSQL";
  database = "prosody";
  username = "mydbuser";
  password = "mydbpass";
  host = "localhost";
}

  myfilestore {
         type = "prosody_files";
         path = "/var/lib/prosody";
  }

  mydatabase {
         type = "prosody_sql";
         driver = "PostgreSQL";
         database = "prosody";
         username = "mydbuser";
         password = "mydbpass";
         host = "localhost";
  }

Running

After defining your stores in the config, you can simply run the migrator:

   prosody-migrator store_one store_two

This will move all the data from ‘store_one’ in the config to ‘store_two’. If no stores are given, ‘input’ and ‘output’ are used by default.

It is also possible to use an alternative config file via the –config option:

   prosody-migrator --config=./mymigratorconfig.cfg.lua

Tips and tricks

If it’s not already obvious from the above - there is no limit on the number of stores you can define in the migrator config. You can use the migrator to move the data between them at any time. This makes it handy for backing up your Prosody database to files, for example, or for moving data between a production and a development Prosody instance, and vice-versa.