Prosody Migrator

Prosody comes bundled with a migration tool to make it easy to move all XMPP server data (user accounts, rosters, vcards, etc.) between different data stores.

Right now the migrator supports Prosody's file-based and SQL backends. In a future release we intend to merge our ejabberd and XEP-0227 migrators into this one.

Building and installing

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 main.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".


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.

Store types


A store with type = "prosody_files" will read/write a Prosody data store using the file-based backend. The only required parameter is 'path', to give the path to the store.


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


The prosody_sql backend is for storing or importing data from an SQL database using Prosody's schema. It requires the LuaDBI library to be installed on the system (as does Prosody itself - see LuaDBI dependency for more information). A message from prosody-migrator that 'prosody_sql' is not an available store type would suggest that LuaDBI is not found.

Available options are:

Name Description
driver (Required) The database driver to use (case-sensitive). Must be one of: SQLite3, PostgreSQL, MySQL
database (Required) The name of the database to connect to (or the filename in SQLite3's case)
username (Optional) The username to authenticate to the database.
password (Optional) The password to authenticate to the database.
host (Optional) The address of the database server to connect to.
port (Optional) The port to connect to the database server on.


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


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.

⚠️ Note that any existing data in the destination store will be overwritten!

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.