Skip to content
JS Support TicketJS Support Ticket Docs

Command line database migration

Help desks that started on an older version can have database tables in the old MyISAM format and the utf8mb3 character set. Both cause trouble:

  • MyISAM locks a whole table while one change is written, so on a busy help desk agents wait for each other. It also has no transactions and no crash recovery.
  • utf8mb3 can’t store four-byte characters, such as the emoji customers put in their e-mails. The database refuses the text or cuts it off at the first one.

The component ships a command line script that converts its tables to InnoDB with the utf8mb4 character set (utf8mb4_unicode_ci). Installing or updating the component also attempts this conversion; the script lets you see what would change first and run it at a time you choose.

The script is administrator/components/com_jssupportticket/cli/migrate.php. It runs only from the command line; opened in a browser, it refuses.

Step 1: see what would change

Section titled “Step 1: see what would change”

From your Joomla site’s root folder, run:

Terminal window
php administrator/components/com_jssupportticket/cli/migrate.php

This changes nothing. It reports:

Line Meaning
Tables found How many help desk tables the database has.
Already converted Tables that are already InnoDB and utf8mb4. They are skipped.
To convert Tables the script would convert.
Blocked Tables it won’t touch, because one of their indexes would be too long for InnoDB with four-byte characters.
Data to rewrite How much data the conversion rewrites, in MB.

Then it lists each table to change, with its current engine and what would be done (“convert to InnoDB”, “convert to utf8mb4_unicode_ci”, or both). Blocked tables show the reason.

If every table is already converted, it says “Nothing to do. Every table is already InnoDB and utf8mb4.” and stops.

Step 2: convert

Section titled “Step 2: convert”

  1. Take a full database backup. MyISAM tables have no transactions, so the backup is the only way back.

  2. Take the site offline, or pick a quiet time. Each table is locked while it is rewritten.

  3. Run the script again with --apply:

    Terminal window
    php administrator/components/com_jssupportticket/cli/migrate.php --apply

  4. When it asks, type migrate and press Enter. Anything else cancels without changing anything.

Each table is converted on its own, and the script prints one line per table: converted, skipped, blocked or failed with the database’s message. At the end it says how many tables it converted and how long it took.

If something goes wrong

Section titled “If something goes wrong”
  • A table failed. The tables that did convert are complete and correct. Fix the cause the message gives (often disk space), then run the script again. Converted tables are skipped, so it carries on where it stopped.
  • A table is blocked. It still works as before; it just keeps its old character set until the index that blocks it is changed.

The script exits with code 0 when everything worked or there was nothing to do, and 1 when a table failed, the conversion was cancelled, or no help desk tables were found.