Fix #117: Enhance migration docs for new db naming

docs/PowerAuth-Mobile-Utility-Server-1.5.0.md

@@ -1,19 +1,69 @@
-## Migration from 1.4.0 to 1.5.x
+# Migration from 1.x.x to 1.5.x
 
-This guide contains instructions for migration from PowerAuth Server version 1.4.0 to version 1.5.x.
+This guide provides step-by-step instructions for migrating from PowerAuth Mobile Utility Server version 1.x.x to
+version 1.5.x.
 
-### Prerequisites
+## Prerequisites
 
-Before performing the migration, users are advised to run the associated Liquibase scripts. Once the Liquibase scripts
-have been executed successfully, proceed with the steps in the "Database Changes" section below and run
-the `1.5.x-migration.sql` script.
+1. **SQL Scripts & Liquibase Tool**: Ensure you have the necessary SQL scripts and the Liquibase tool available.
+   Depending on your database type, the scripts can be found at:
 
-### Database Changes
+    - Oracle: `${repo_root}/docs/sql/oracle`
+    - PostgreSQL: `${repo_root}/docs/sql/postgresql`
 
-#### Data Migration between Tables
 
-Migration involves copying data from old tables to new tables and subsequently deleting the old tables. Below are the
-SQL commands used for this process:
+2. **Docker DB Update Script**: Before running the script `docker-db-update.sh`, ensure that you have set up the
+   required environment variables. For a list of the required environment variables or additional details, refer to the
+   associated documentation [Deployment.md](Deployment.md).
+
+## Migration Steps
+
+1. **Stop the Application**: Ensure that the PowerAuth Mobile Utility Server application is not running. Shut it down if
+   it's currently active.
+
+
+2. **Backup the Database**: Before making any changes, it's crucial to **back up your database**. This step ensures you have
+   a fallback in case of any unforeseen issues.
+
+   > **IMPORTANT**: Ensure that you've backed up your entire database before proceeding
+
+
+3. **Execute Pre-Migration Script**: Navigate to the appropriate SQL scripts directory based on your database type. Run
+   the `1.5.x-migration-before.sql` script.
+
+
+4. **Run Liquibase Commands with Docker**: To apply the database changes, execute the `docker-db-update.sh` script.
+   Please take a look at a list of necessary environmental variables listed
+   here [env.list.tmp](../deploy/env.list.tmp).
+
+
+5. **Execute Post-Migration Script**: After applying the Liquibase changes, run the `1.5.x-migration-after.sql` script
+   located in the same directory as the pre-migration script.
+
+
+6. **Start the PowerAuth MUS Application**: Once all the database changes are successfully applied, restart the
+   PowerAuth Mobile Utility Server application.
+
+## Database Changes - detailed description of changes above
+
+The steps detailed above have taken care of migrating the database structure. The following is an overview of the major
+changes:
+
+### Resetting Liquibase Tracking Tables
+
+Liquibase uses specific tables to track which changesets have been applied to the database. Occasionally, to ensure a
+fresh start or to reset its state, these tables might need to be dropped. The `1.5.x-migration-before.sql` script takes
+care of this by removing the following Liquibase-specific tables:
+
+```sql
+-- Drop liquibase tracking tables
+DROP TABLE databasechangelog CASCADE;
+DROP TABLE databasechangeloglock CASCADE;
+```
+
+### Data Migration between Tables
+
+The migration involves transferring data from old tables to new ones. Post data transfer, the old tables are discarded.
 
 ```sql
 -- Migrate data
@@ -41,9 +91,10 @@ INSERT INTO mus_certificate SELECT * FROM ssl_certificate;
 INSERT INTO mus_localized_text SELECT * FROM ssl_localized_text;
 ```
 
-#### Drop Old Tables
+### Removal of Deprecated Tables and Sequences
 
-After successful data migration, the old tables are no longer required and can be dropped:
+After the data migration is successfully completed, the old tables and their associated sequences, which are no longer
+in use, have been removed.
 
 ```sql
 -- Drop old tables
@@ -54,23 +105,18 @@ DROP TABLE ssl_mobile_app_version CASCADE;
 DROP TABLE ssl_mobile_domain CASCADE;
 DROP TABLE ssl_user CASCADE;
 DROP TABLE ssl_user_authority CASCADE;
-```
-
-#### Drop Old Sequences
 
-Similarly, old sequences associated with the dropped tables can be removed:
-
-```sql
 -- Drop old sequences
 DROP SEQUENCE ssl_certificate_seq CASCADE;
 DROP SEQUENCE ssl_mobile_app_seq CASCADE;
 DROP SEQUENCE ssl_mobile_app_version_seq CASCADE;
 DROP SEQUENCE ssl_mobile_domain_seq CASCADE;
 DROP SEQUENCE ssl_user_authority_seq CASCADE;
 DROP SEQUENCE ssl_user_seq CASCADE;
+
 ```
 
 ### Conclusion
 
-After executing the above SQL commands successfully, the migration process is complete. Ensure to verify and test the
-updated database to confirm the successful migration from version 1.4.0 to 1.5.x.
+Upon successfully executing the provided SQL commands and scripts, the migration process is complete. Ensure to verify
+and test the updated database to confirm the successful migration from version 1.x.x to 1.5.x.

docs/sql/oracle/1.5.x-migration-before.sql

@@ -0,0 +1,4 @@
+-- Drop liquibase tracking tables
+DROP TABLE databasechangelog CASCADE CONSTRAINTS;
+DROP TABLE databasechangeloglock CASCADE CONSTRAINTS;
+

docs/sql/postgresql/1.5.x-migration.sql → docs/sql/postgresql/1.5.x-migration-after.sql

@@ -40,4 +40,3 @@ DROP SEQUENCE ssl_mobile_app_version_seq CASCADE;
 DROP SEQUENCE ssl_mobile_domain_seq CASCADE;
 DROP SEQUENCE ssl_user_authority_seq CASCADE;
 DROP SEQUENCE ssl_user_seq CASCADE;
-

docs/sql/postgresql/1.5.x-migration-before.sql

@@ -0,0 +1,3 @@
+-- Drop liquibase tracking tables
+DROP TABLE databasechangelog CASCADE;
+DROP TABLE databasechangeloglock CASCADE;