When opening a Knowledge Base from GeneXus 17 Upgrade 5 or higher, if you use an older version of GeneXus, it will automatically import the new version of GAM (4.0.5). A Build performed from the IDE will automatically execute a reorganization of the database and a metadata migration immediately after that.
While in the Development environment, the update is performed automatically and transparently, the database update in the Production environment requires, the developer to execute it.
The steps for performing the update in the Production environment are:
- Reorganize the database. To this end, the SQL script content is distributed in the GeneXus installation in the following path: <GX_installation_path>\Library\GAM\Platforms\<environment>\ReorganizationScript404To405.txt
Note: The execution of the reorganization process must be incremental. When migrating from version prior to 4.0.4, you must execute each reorganization in order, starting by the one that follows your version.
- To complete the upgrade, migrate the metadata using the GAM Deploy Tool (GDT) through the command line.
To run this migration, write permissions are required in the directory of execution. This applies only to the migration of the connection.gam file.
It varies depending on the environment where the invocation of the GDT is located. The connection.gam file is generated in the directory that runs the GDT:
NET: In the directory <KB>\<Net_env>\web\bin the exe is distributed.
agamdeploytool.exe -upgradegam -admin_name gamadmin -admin_pass gamadmin123
JAVA: In the directory <TOMCAT_DIR>\webapp\<App_Name>\WEB-INF\classes\<path_to_package> the class is distributed.
Before running the GDT, copy the connection file from <TOMCAT_DIR>\webapps\<APP>\WEB-INF\connection.gam to <TOMCAT_DIR>\webapps\<APP>\WEB-INF\classes\<Path_to_package> (for example, C:\Program Files\Apache Software Foundation\Tomcat 8.5\webapps\AppJavaSQL\WEB-INF\classes\com\test).
Then, run the GDT:
java -cp "<TOMCAT_DIR>\webapp\<App_Name>\WEB-INF\classes\lib\*" genexus.security.api.agamdeploytool -upgradegam -admin_name gamadmin -admin_pass gamadmin123
NETCORE: In the directory <KB>\<NetCore_env>\web\bin the library is distributed.
dotnet agamdeploytool.dll -upgradegam -admin_name gamadmin -admin_pass gamadmin123
- If the GDT runs successfully, then the closing lines must be:
Connecting to GAM database ...
Data migration from 4.0.4 to 4.0.5
- To move the new file to production:
- If the application is deployed in a container, you can set an environment variable. Open the connection.gam file generated by the tool, obtain the value of the "<key>" tag, and configure it as indicated in the document: support setting key for GAM connection data through environment variable.
- Otherwise, copy the newly generated connection.gam file to the corresponding location according to the environment:
The file is generated in the directory <KB>\<Net_env>\web\bin. Copy it to the directory <KB>\<Net_env>\web.
Note that there is a backup of the old connection.gam file called connection-bkp.gam.
Copy the connection file generated in <TOMCAT_DIR>\webapps\<APP>\WEB-INF\classes\<Path_to_package>\connection.gam to <TOMCAT_DIR>\webapps\<APP>\WEB-INF.
Similar to Net but in the NetCore environment, <NetCore_env>.
The GAM database is fully backward compatible. This means that you may continue using KBs with a GeneXus version prior to v17u5 pointing at a new database.