upgrade doc: workaround procedure to restore roles table (issue #61)

doc/admin/upgrading/README.md

@@ -53,10 +53,39 @@ php artisan migrate
 
 ***Step 6: Seed functionality tables***
 
+Currently, Voyager has a limitation regarding deployment of BREAD functionalities. The developers are working on this and things should be easier after the v2.0 release of Voyager. Before this is implemented, you need to use the following procedure to update the functionality tables.
+
+Make a backup of the users and roles table (these copies will not have foreign keys), and empty the actual users table. For this, type the following (change `admin` by the login you set when installing the database):
+```sh
+mysql -u admin -p
+```
+Enter the password when prompted. This will bring you in a SQL shell.
+Once there type:
+```sql
+mysql> USE labstocks_db;
+mysql> CREATE TABLE IF NOT EXISTS users_bckp SELECT * FROM users;
+mysql> CREATE TABLE IF NOT EXISTS roles_old SELECT * FROM roles;
+mysql> DELETE FROM users WHERE id > 0;
+mysql> exit ;
+```
+Now update the functionality tables by running this command which will call the corresponding seeders:
+
 ```sh
 ./restorefunctionalitytables.sh
 ```
 
+Restore the users table from backup, without their roles if the roleid changed during the update of the roles table. For this, reconnect into MySQL as above and once there, type:
+
+```sql
+mysql> USE labstocks_db;
+mysql> UPDATE users_bckp SET role_id=NULL WHERE role_id NOT IN ( SELECT id FROM roles WHERE id IN (SELECT id from roles_old) ) ;
+mysql> INSERT users SELECT * FROM users_bckp ;
+mysql> DROP TABLE roles_old , users_bckp ;
+mysql> exit ;
+```
+
+Some users may now have no role. You will need to attribute them a role manually from the admin panel (see below) so that they can log in. Otherwise, login will be refused and Voyager will redirect them to the / route.
+
 ***Step 7: Clear all caches***
 
 First these three ones:
@@ -79,6 +108,10 @@ If you get an error `Failed to clear cache. Make sure you have the appropriate p
 php artisan up
 ```
 
+***Step 9: Update roles attribution to users who lost their default role***
+
+As indicated above, some users may now have no role because the role they had is no longer valid after the upgrade. From the admin panel, browse the users table and look for NULL entries in the role attribute. Edit these users to assign them a role of your choice.
+
 ***Additional step if you are upgrading from v2.0.1***:
 
 If you are upgrading from v2.0.1, you need to install additional prerequisites for plasmid map drawing (based on cirdna):