Upgrade from 1.x to 2

This describes a manual way of upgrading from version 1 to 2 and then upgrading to version 3.

During the upgrade process, there is a chance that migrations may fail. Therefore, it is wise to have a backup that you can import to start over at any time. Backup your database! Store a copy somewhere safe.

Set up an additional environment and perform the upgrade there. Keep production running until you confirm the upgrade

Contact support to obtain a 2.x version

Use PHP 8.2 or 8.3 for the best results. This means you need PHP 7.4 and 8.x at the same time. Leave PHP 7.4 as default to not interfere with production when working on the same machine. On a separate machine you don't have to worry about that.

You should be able to connect to the database with a database management tool. One that could work for you is DBeaver.

The upgrade process

Some of the steps will throw an error this is expected. If there is any error that is not described here, feel free to contact support.

1. Download version 2.x of MailScheduler

2. Place the extracted files in a folder. This will be the working directory

3. Run the install.bat script.

4. Now you should see a .env file. Update the database credentials in the .env file.

5. Run php mail-scheduler-2.phar migrate

6. If you receive the error 'Attempt to read property "session_site" on null', you should add a Tableau Personal Access Token to the tokens table:

   1. id: Note the id, we need it in the next step

   2. label: free field. Your label

   3. pat_name: Personal Access Token name, should be exactly similar to the token you created

   4. pat_secret: Personal Access Secret name, should be exactly similar to the token you created

   5. session_site: Leave empty

   6. session_expires_at: Leave empty

7. Look into the sites table, for every site you have to add the token id. If you have different site, it is wise to use a different token for every tableau site name.

8. Run the migration again until it completes without errors. Report any remaining errors to support:

   1. Provide a screenshot of the console

   2. Copy where possible the error message in the ticket.

   3. Add as much relevant data and tables as possible for a quick response

9. If the migration was successful we can focus on the schedules migration.

10. Rerun the following command until all schedules are converted: Run: php mail-scheduler-2.phar migrate-from-v1-to-v2

Known issues and how to fix those

Cannot drop index 'PRIMARY': needed in a foreign key constraint

Error: SQLSTATE[HY000]: General error: 1553 Cannot drop index 'PRIMARY': needed in a foreign key constraint (SQL: ALTER TA BLE site_user CHANGE group_id site_id INT UNSIGNED NOT NULL)

Fix: Run these SQL commands (for mysql):

-- Rename foreign keys before modifying the column ALTER TABLE site_user DROP FOREIGN KEY group_user_group_id_foreign; ALTER TABLE site_user DROP FOREIGN KEY group_user_user_id_foreign;

-- Rename group_id to site_id ALTER TABLE site_user CHANGE group_id site_id INT(10) UNSIGNED NOT NULL;

-- Recreate foreign key constraints with the new column name ALTER TABLE site_user ADD CONSTRAINT site_user_site_id_foreign FOREIGN KEY (site_id) REFERENCES sites (id) ON DELETE CASCADE, ADD CONSTRAINT site_user_user_id_foreign FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE;