what is the proper way to backup/restore a mnesia database?

I had a pretty hard time getting this to work, so I'll share the steps I went through.

Start by backing up the node in the distributed system that you want to restore (to a single node):

> mnesia:backup("/path/to/backup").

Make sure the following adaptation of change_node_name is available on the node you want to restore to:

-module(move_backup).
-export([set_node_name/4]).                                                                                                    

set_node_name(From, To, Source, Target) ->
    Switch =
        fun (Nodes) ->
                case lists:member(From, Nodes) of
                    true -> [To];
                    false -> []
                end
        end,
    Convert =
        fun({schema, db_nodes, Nodes}, Acc) ->
                {[{schema, db_nodes, Switch(Nodes)}], Acc};
           ({schema, version, Version}, Acc) ->
                {[{schema, version, Version}], Acc};
           ({schema, cookie, Cookie}, Acc) ->
                {[{schema, cookie, Cookie}], Acc};
           ({schema, Tab, CreateList}, Acc) ->
                Keys = [ram_copies, disc_copies, disc_only_copies],
                OptSwitch =
                    fun({Key, Val}) ->
                            case lists:member(Key, Keys) of
                                true -> {Key, Switch(Val)};
                                false-> {Key, Val}
                            end
                    end,
                {[{schema, Tab, lists:map(OptSwitch, CreateList)}], Acc};
           (Other, Acc) ->
                {[Other], Acc}
        end,
    mnesia:traverse_backup(Source, Target, Convert, switched).

Convert the backup:

> move_backup:set_node_name('before@host', 'after@host', "/path/to/backup", "/path_to_backup_converted").

I'm going to assume that the new node is completely empty (if this is not the case, you might want to change the default_op argument). There are two options, one for a live restore:

> mnesia:restore("/path/to/backup_converted", [{default_op, recreate_tables}]).

which is great but might use a lot of memory if you have a large database (mine was ~10GB so this caused an out of memory exception). The alternative is to install a fallback, and restart your shell:

> mnesia:install_fallback("/path/to/backup_converted").
> q().

then when you restart the shell (assuming you're using the right node name) it will import the full database.

I think that this problem falls in the broader category of Mnesia questions that are related to a simple one:

How do I rename a Mnesia node?

The first and simplest solution, if your db is not huge, is to use the mnesia:traverse_backup function (see Mnesia User guide). Following is an example from the Mnesia User guide:

change_node_name(Mod, From, To, Source, Target) ->
    Switch =
        fun(Node) when Node == From -> To;
           (Node) when Node == To -> throw({error, already_exists});
           (Node) -> Node
        end,
    Convert =
        fun({schema, db_nodes, Nodes}, Acc) ->
                {[{schema, db_nodes, lists:map(Switch,Nodes)}], Acc};
           ({schema, version, Version}, Acc) ->
                {[{schema, version, Version}], Acc};
           ({schema, cookie, Cookie}, Acc) ->
                {[{schema, cookie, Cookie}], Acc};
           ({schema, Tab, CreateList}, Acc) ->
                Keys = [ram_copies, disc_copies, disc_only_copies],
                OptSwitch =
                    fun({Key, Val}) ->
                            case lists:member(Key, Keys) of
                                true -> {Key, lists:map(Switch, Val)};
                                false-> {Key, Val}
                            end
                    end,
                {[{schema, Tab, lists:map(OptSwitch, CreateList)}], Acc};
           (Other, Acc) ->
                {[Other], Acc}
        end,
    mnesia:traverse_backup(Source, Mod, Target, Mod, Convert, switched).

view(Source, Mod) ->
    View = fun(Item, Acc) ->
                   io:format("~p.~n",[Item]),
                   {[Item], Acc + 1}
           end,
    mnesia:traverse_backup(Source, Mod, dummy, read_only, View, 0).

The most important part here is the manipulation of the {schema, db_nodes, Nodes} tuple which let you rename or replace the db nodes.

BTW, I've used that function in the past and one thing I noticed is that the backup terms format changes between mnesia versions, but maybe it was simply me writing bad code. Just print a backup log for a small mnesia database to check backup term format, if you wanna be sure.

Hope this helps!