Why GLPI database conversion to InnoDB and utf8mb4 matters before an upgrade
Converting an older GLPI database from MyISAM to InnoDB and from utf8 to utf8mb4 is a prerequisite you should plan before a move to a newer GLPI release, not an optional clean-up. The console provides four migrations for this work: glpi:migration:myisam_to_innodb, glpi:migration:dynamic_row_format, glpi:migration:utf8mb4 and glpi:migration:unsigned_keys. Run them against a copy of your production database first, and treat the result as a change to the database schema, with its own test cycle and rollback point, rather than as a file copy.
The order matters. The dynamic_row_format migration is required before utf8mb4 can be applied, because longer multibyte characters can push row sizes past the limits of the older row format. The myisam_to_innodb migration moves storage engines so that the database has transactional behavior and row-level locking. The unsigned_keys migration aligns key column types, which should be reviewed alongside the upgrade so that any custom tables, reports or plugin schemas that reference those keys are checked as well. Each step changes tables that your plugins and integrations may query directly, so inventory those dependencies before you start.
Before you schedule the work, confirm three things with your own environment: the MySQL or MariaDB version you run against the prerequisites listed in the GLPI installation docs, the size of your largest tables (particularly glpi_logs), and whether your backups can restore a full copy within your maintenance window. Those answers determine whether the console tools are enough or whether you need the Percona approach covered later on this page. A database that has never been converted is also a common reason an upgrade stalls, so finding out early gives your team time to fix it on its own schedule.
What each database conversion changes and what you must do
This table compares the four console conversions and the glpi_logs size threshold, showing what each changes in the database and what you must do before running it. Read each row alongside the GLPI CLI documentation and the version of MariaDB or MySQL you run, because exact effects depend on both. The main takeaway is that every conversion should be rehearsed on a restored copy of production first.
| Change | Impact | Action needed |
|---|---|---|
| MyISAM to InnoDB | MyISAM tables lack transactions and row-level locking, so writes can block reads under concurrent ticket and asset activity. InnoDB adds transactional storage and crash recovery. | Confirm the engine of each table before conversion. Take a full backup, run the console command on a copy, and check table counts and application behavior afterward. |
| Dynamic row format | Required before utf8mb4 can be applied to indexed columns in the affected tables. Changes how long values are stored on the page. | Run the dynamic row format command before the utf8mb4 command. Confirm the InnoDB settings your MariaDB or MySQL version requires for it. |
| utf8 to utf8mb4 | Adds full Unicode support, including emoji and some supplementary characters that the older utf8 charset cannot store. Index and row sizes grow, which can affect long indexed columns. | Check for text that already fails to store, review index lengths, and confirm the collation you want. Run the conversion on a copy and check long fields such as ticket content. |
| Unsigned keys | Changes integer key columns to unsigned types, which matches how GLPI identifiers are used and stores larger positive ranges. Foreign key pairs must change together. | Confirm the migration handles every related key column. Check custom plugin tables and reports that read these columns, since their types will change. |
| glpi_logs table larger than 5 GB | GLPI's Help Center suggests pt-online-schema-change from Percona Toolkit as more efficient and safer than the bin/console tools for this size. Standard console runs on this table can lock it for a long period. | Measure the table size before starting. If it exceeds the threshold, plan a Percona Toolkit run, test it on a copy, and confirm disk space for the temporary copy. |
How the GLPI console migrations run in order
The four glpi:migration commands in the GLPI console are not interchangeable, and their order matters. The usual sequence is to convert tables from MyISAM to InnoDB first, then enable the dynamic row format, then convert the character set to utf8mb4, and finally correct unsigned keys. Each command runs through bin/console from the GLPI installation directory, so the PHP user and file permissions must match the existing install. Before running anything, confirm the exact command names, options and recommended order against the GLPI command-line interface documentation for your target GLPI version, because option names and prerequisites can change between releases.
The reason dynamic row format must come before utf8mb4 is index length. InnoDB limits index key size, and a utf8mb4 character can take up to four bytes, so indexed string columns that fit under utf8 can exceed the limit once converted. The dynamic row format raises that limit for affected tables. Running the character set conversion first can leave tables that fail or that are only partly converted, which is why the row format step is a prerequisite rather than an optional tidy-up. Ask your DBA to check the current innodb_default_row_format and innodb_large_prefix-era settings on your server version before the first run.
Run the whole sequence on a restored copy of the production database, not on the live instance. Each command rewrites large tables, and a failure partway through leaves the schema mixed, with some tables converted and others not. A copy lets you time the run, confirm GLPI still loads, check ticket and asset pages, and roll back cheaply if a step fails. Take a fresh backup of the database, the files and the config directory, including glpi.key and glpicrypt.key, immediately before the production run.
What to back up and check before converting tables
Table conversions rewrite every row of the GLPI database, so a failed run is only recoverable if the starting point is known good. The six items below cover what to protect, what to test and what to confirm before the console commands touch production data.
Full database backup
Take a complete dump of the GLPI database before any conversion step, and confirm it can be read back. The conversion commands alter table engines, row formats and character sets in place, so a dump is the only clean way back if a step stops partway. Record the time the dump was taken and the GLPI version that produced the data, so you can match the backup to the code that will restore it. Check that the dump includes every table, including the large glpi_logs table, rather than a partial export.
Files and config directory copy
Copy the GLPI application files, the files directory and the config directory, including glpi.key and glpicrypt.key. Those keys encrypt stored secrets, so a database restore without them leaves credentials and encrypted fields unreadable. Store the copy outside the web root and restrict its permissions. Keeping the file tree alongside the database dump means a rollback restores the code and data that were working together.
Restored test copy
Restore the database dump and the file copy into a separate environment and run the conversion there first. This shows how long each step takes on your data, which tables fail or warn, and whether GLPI loads correctly afterward. Compare row counts and open a sample of tickets, assets and logs before and after. Run the conversions on the test copy at least once before you touch production, and treat the test timings as the basis for your maintenance window.
Plugin, index and charset inventory
List every installed plugin, every custom index and every table or column with a non-default character set or collation. Plugins that create their own tables may not be converted by the core commands, and custom indexes can block a dynamic row format change or a key conversion. Note any column that stores multibyte text so you know where utf8mb4 matters most. Ask each plugin vendor whether its tables are compatible with utf8mb4 and InnoDB before the conversion starts.
Database server version checks
Confirm the MariaDB or MySQL version against the GLPI prerequisites for your target release, and confirm the server runs InnoDB with the settings your conversion needs. The GLPI README and installation docs list different minimums, so check the version for the exact GLPI release you plan to run after the conversion. Also confirm the database user has the privileges to alter tables, and check free disk space, because InnoDB conversions can temporarily need substantially more room than the data itself.
Maintenance window and user notice
Schedule a window long enough for the backup, the conversion steps and a verification pass, and tell users that GLPI will be unavailable or read-only during that time. Stop automatic actions and queued notifications so no writes land in tables mid-conversion. Agree on who approves go-live, who can call a rollback and what the rollback trigger is. Keep the window in your change calendar so other maintenance does not overlap it.
How to run the conversion on a restored copy first
This sequence proves each database conversion step on an isolated copy of production data, so the team knows the order, the runtime behavior and the rollback point before anything touches the live GLPI instance.
Take a full backup of production
The database administrator dumps the GLPI database and the team copies the files and the config directory, including glpi.key and glpicrypt.key, before any change. Keep the dump in a location the conversion host cannot overwrite. This backup is the first rollback point, and it is done when the team has confirmed the dump file opens and its size and table count match the source. Without the key files, encrypted values in the restored instance cannot be read, so confirm they are in the same backup set.
Restore the backup to an isolated copy
Load the dump into a separate database server or a separate database on the same server that no GLPI web server or agent can reach. Point a copy of the GLPI application at it with the copied config directory, and confirm that the copy never receives notifications, inventory uploads or scheduled tasks from production. The step is complete when the copy loads a login page and the team can sign in with a test account. Record the row counts of the largest tables, since these will be compared after each stage.
Check server version and table status
Confirm the database server version and the GLPI version on the copy against the GLPI prerequisites for the release you are moving to. Then list the storage engine, row format and character set of every table, and note which tables still use MyISAM, the older row formats or utf8 instead of utf8mb4. Check the size of glpi_logs as well, because very large tables change the approach described later on this page. The output is a saved inventory of table states that becomes your baseline for comparison.
Run the MyISAM to InnoDB migration on the copy
On the copy, run the console command glpi:migration:myisam_to_innodb from the GLPI installation directory, then repeat the table status check. Confirm the exact command syntax, options and any required flags in the GLPI command-line interface documentation before running it. The step is done when no GLPI table reports MyISAM and the row counts match the baseline. If the command fails or counts differ, stop, discard the copy, and restore the backup to try again with a corrected approach.
Apply the dynamic row format
Run glpi:migration:dynamic_row_format on the copy. The GLPI documentation treats this step as required before utf8mb4 conversion, so it is not optional if you plan to move the character set. Verify the row format of the tables afterward and confirm the row counts again. This is the second rollback point: if later steps fail, restoring the backup and repeating from this stage is the fastest path, and the team should note the time each stage takes on the copy.
Convert tables to utf8mb4
Run glpi:migration:utf8mb4 on the copy, then check the default character set and collation of the database and of the converted tables. Run a few searches that include accented characters or non-Latin text, and open tickets and assets whose names contain them, to confirm the data reads back correctly. Confirm the command's behavior and any required flags in the GLPI documentation first. The step is complete when the table character sets report utf8mb4 and the sample records display without corruption.
Convert keys to unsigned and verify GLPI
Run glpi:migration:unsigned_keys on the copy and confirm the key columns changed as the documentation describes. Then test GLPI on the copy: sign in, open a ticket, view an asset with its relations, run a search, generate a report, and trigger a scheduled task manually. Check the web server and PHP error logs for database warnings. The conversion is verified when the key pages load without errors and the row counts still match the baseline. Only then is the same sequence considered ready for a planned window on production.
Record rollback points and confirm before production
Write down the outcome, the command output and the duration of each stage on the copy, and mark which backup each rollback point depends on. Ask the GLPI support or your database administrator to confirm any production-specific differences, such as replication, plugin tables or the presence of very large logs that call for Percona tools. Repeat the full sequence on a fresh restore to confirm it is repeatable. Production work starts only when the record shows each stage passed in order and the team has a tested restore path for every point.
When Percona pt-online-schema-change fits better than console tools
The GLPI Help Center suggests using pt-online-schema-change from Percona Toolkit instead of the bin/console migration commands when the glpi_logs table is larger than 5 GB. The Help Center describes this route as more efficient and safer for tables of that size, because the console tools rewrite the table in place while the application keeps running against it. Before you choose a method, measure the size of glpi_logs and the other large tables in your database, including their data and index sizes, and record the figures. The 5 GB threshold is the Help Center's guidance, so confirm your own numbers against it rather than assuming a table falls under or over the line.
Percona is a separate toolchain with its own operational demands. Your team has to install Percona Toolkit on a host that can reach the database, verify the version against your MySQL or MariaDB server, and grant the account the privileges the tool needs. The conversion itself runs as a different procedure from the console commands, with its own steps for triggers, progress checks and cleanup of the shadow table if something stops partway. Someone in your team must own that procedure, understand how it interacts with GLPI's scheduled tasks and logging, and be able to explain it to an auditor or a change board.
Run the full Percona procedure on a copy of the production database before you touch production, and time it against your change window. Confirm the exact steps, options and any post-run cleanup in the Help Center procedure, which is the source your team should follow for this table. A test copy also shows whether the table conversion and the glpi:migration commands that follow leave GLPI in the state you expect. Ask your database administrator to confirm backup and rollback steps, and agree in writing who signs off the result.
What makes a GLPI charset and engine conversion take longer
This table lists the factors that stretch or shrink a MyISAM to InnoDB and utf8mb4 conversion on a GLPI database. Read each row against your own database before estimating effort, since the largest tables and any replicas usually set the schedule. Size and the glpi_logs table are the first thing to measure.
| Driver | Effect on effort | What to check |
|---|---|---|
| Database size, especially glpi_logs above 5 GB | Large tables take longer to rebuild and raise the risk of a failed run, so the Help Center points to Percona tooling for these cases | Measure table sizes and row counts per table, and flag glpi_logs if it exceeds 5 GB |
| Number of tables still on MyISAM | Each MyISAM table is converted separately, so more tables mean more console runs and more verification | List tables by engine and confirm which ones the console command will touch |
| Custom plugin tables and indexes | Plugin tables may not follow core conventions, which can block conversion or need manual index work | Ask plugin authors or vendors about engine, charset and key definitions before the run |
| Replication or database replicas | Engine and charset changes must reach every replica, and replication lag can extend the window | Confirm your replica topology, replication format and how changes will be applied to each node |
| Availability window | A GLPI instance in use cannot safely be changed mid-run, so a tight window forces staged or tool-assisted work | Agree the maintenance window with service desk owners and confirm backup and rollback timing |
| Server hardware and storage headroom | Rebuilding tables needs free disk space and I/O capacity, and a short on-disk margin can stop the job | Check free space for the largest tables plus temporary space, and confirm disk I/O under load |
| Number of environments needing the same conversion | Each environment repeats the work, so test-to-production copies multiply effort unless the steps are scripted | Count production, staging, test and disaster recovery copies and decide which runs are repeatable |
Questions buyers ask before converting a GLPI database
How much does a GLPI database conversion cost, and what drives the price?
The price follows from the written scope, not from a standard rate. Cost has three parts: the assessment of your current schema and plugins, the conversion runs on a test copy, and the production cutover with its backup and verification. The largest drivers are database size, how many tables still use MyISAM, the number of installed plugins that add their own tables, and whether large log tables need Percona tooling. The conversion is a one-time piece of work, while ongoing maintenance of the database is a separate recurring item. No public price is given for this work, so request a quote based on a written scope that names each of these components.
How long does a MyISAM to InnoDB conversion take?
Duration is set by table size and the number of rounds needed on a test copy, not by the console commands alone. The window is driven by the size of the largest tables, especially glpi_logs, the write rate on the live instance during the cutover, and how many fixes are needed after plugin tables are converted. GLPI's Help Center notes that tables above 5 GB in glpi_logs warrant a different approach, so measure your table sizes first. Ask for the planned test runs, the rollback point and the maintenance window the scope assumes, and confirm the timing against a restore of your own database.
What does the work need from our team?
Your team provides access, decisions and time in a maintenance window. In practice that means:
- A full backup of the database, the GLPI files and the config directory, including
glpi.keyandglpicrypt.key, verified by a test restore. - A test copy of the production database on infrastructure with the same MySQL or MariaDB version.
- Database and server access for the engineers, plus a list of installed plugins and their owners.
- An agreed maintenance window and a named person who can approve go or no-go at cutover.
Ask the provider to list these inputs in the written scope so gaps are visible before work starts.
Can our internal team convert the database without outside help?
Yes, if the team has MySQL or MariaDB administration skills, a tested backup and restore process, and time to test on a copy. The console commands are documented in GLPI's CLI reference, so the work is not secret. The risk lies in plugin tables, custom indexes and the judgment needed when a step fails halfway. Teams that choose to do it internally should still rehearse the full procedure on a copy and record each step. Ask a partner for a scope only if you want the rehearsal, verification and cutover handled to a written plan.
When are Percona tools worth the extra setup?
Percona tools are worth the setup when the GLPI Help Center's threshold applies to your database. For databases whose glpi_logs table exceeds 5 GB, the Help Center suggests pt-online-schema-change from Percona Toolkit as more efficient and safer than the bin/console tools. Below that size, the built-in console commands are usually the simpler path, though you should still test them on a copy. The extra setup includes installing the toolkit, checking privileges and planning how the online change will be monitored and finished. Confirm the table sizes and the Help Center procedure against your own version before deciding.
What happens if a conversion step fails in production?
A failed step should stop the run and send the team to the rollback point, which is the verified backup taken before any change. Because the console commands alter tables in place, the safe response is to restore from that backup rather than try to repair a partly converted schema by hand. The written scope should say who makes the go or no-go call, how long a restore takes on your hardware, and how the team verifies the instance after a restore. Ask for a documented rollback test on the copy before the production run.
How DeployOpen scopes and delivers GLPI database conversions
DeployOpen treats the MyISAM to InnoDB and utf8mb4 conversion as a planned change to a production database, not a console session. The work is scoped in writing, rehearsed on a copy of your GLPI database, and run inside infrastructure you control.
How we scope
- Inventory table engines, collations and glpi_logs size before agreeing the conversion order.
- Confirm PHP, MariaDB or MySQL versions and the GLPI release the database must match.
- Agree in writing whether Percona Toolkit is in scope for large log tables and who approves it.
How we build
- Take a full database and file backup, including glpi.key and glpicrypt.key, before any change.
- Rehearse the glpi:migration commands on a restored copy and record timings and errors.
- Run dynamic row format before utf8mb4, and check unsigned key results against your plugin schema.
How we hand over
- Provide a runbook listing each console command, its order, expected output and rollback point.
- Document verification queries that confirm engines, row formats, character sets and key types.
- Record which tables were converted by which method, so later GLPI upgrades start from a known state.
How we support
- Fixed-scope engagements end with agreed deliverables, not open-ended tuning of your database.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Your team keeps administrative control of the database, backups and infrastructure throughout.
