Questions about the correct use of the schema() and upgrade() methods.
Posted: 01 Dec 2025, 17:16
Hello!
I'm developing a plugin for MantisBT (currently my version is 2.5.1, but my company intends to update). My intention is to do everything in the best way possible, using everything that MantisBT itself provides.
My plugin needs to make some changes to the database (MySQL), actually creating some stored procedures, and today I simply execute my creation code in the install() method and my removal code in the uninstall() method. However, I know that there is, at least for installation, the possibility of using the schema() and upgrade() methods; the problem is that I haven't found instructions anywhere on how to use these methods, and what I understood from them is that the updates are incremental and defined by entries in an array returned by schema(), and that the upgrade() method is a way to validate a step in the execution of one of these evaluations, that is, for each item in the array returned by schema(), the upgrade() method is executed BEFORE as a way to execute PREVIOUS steps and perform validations. I understood this from reading the code, but it completely contradicts the documentation for the upgrade() method:
Another unclear point is what information can be included in the array returned by the schema() method. In the code, I only saw "InsertData", "UpdateSQL", and "UpdateFunction", but the documentation for the schema() method (MantisPlugin class) references other things like "CreateTableSQL", "AddColumnSQL", "CreateIndexSQL"... Looking at the code, I see that when it's not "InsertData", "UpdateSQL", or "UpdateFunction", the execution is delegated to an instance of an object created by "NewDataDictionary", and I believe it serves to execute methods of ADODB_DataDict and ADODB2_mysql directly. Is there somewhere I can find more information about using these functions?
Another question is: these operations performed via schema/upgrade only INCREMENT the database. When I uninstall the plugin, the changes are not undone. Are there any automated ways to undo what was done when uninstalling a plugin? Are there at least functions that could be called to facilitate this process?
I imagine that if it doesn't exist, I'll have to keep a record of what's been done and undo it myself, but since I want to do it in the best way possible, I came here to ask.
I'm developing a plugin for MantisBT (currently my version is 2.5.1, but my company intends to update). My intention is to do everything in the best way possible, using everything that MantisBT itself provides.
My plugin needs to make some changes to the database (MySQL), actually creating some stored procedures, and today I simply execute my creation code in the install() method and my removal code in the uninstall() method. However, I know that there is, at least for installation, the possibility of using the schema() and upgrade() methods; the problem is that I haven't found instructions anywhere on how to use these methods, and what I understood from them is that the updates are incremental and defined by entries in an array returned by schema(), and that the upgrade() method is a way to validate a step in the execution of one of these evaluations, that is, for each item in the array returned by schema(), the upgrade() method is executed BEFORE as a way to execute PREVIOUS steps and perform validations. I understood this from reading the code, but it completely contradicts the documentation for the upgrade() method:
So, I'm confused because even looking at the files from the latest version of MantisBT, both the behavior of the schema and upgrade methods, as well as this comment (PHPDoc), remain the same. Therefore, I wanted to know if my interpretation is correct.This callback is executed after the normal schema upgrade process has executed. This gives your plugin the chance to convert or normalize data after an upgrade.
Another unclear point is what information can be included in the array returned by the schema() method. In the code, I only saw "InsertData", "UpdateSQL", and "UpdateFunction", but the documentation for the schema() method (MantisPlugin class) references other things like "CreateTableSQL", "AddColumnSQL", "CreateIndexSQL"... Looking at the code, I see that when it's not "InsertData", "UpdateSQL", or "UpdateFunction", the execution is delegated to an instance of an object created by "NewDataDictionary", and I believe it serves to execute methods of ADODB_DataDict and ADODB2_mysql directly. Is there somewhere I can find more information about using these functions?
Another question is: these operations performed via schema/upgrade only INCREMENT the database. When I uninstall the plugin, the changes are not undone. Are there any automated ways to undo what was done when uninstalling a plugin? Are there at least functions that could be called to facilitate this process?
I imagine that if it doesn't exist, I'll have to keep a record of what's been done and undo it myself, but since I want to do it in the best way possible, I came here to ask.