Quick links
On this page:
Related topics:
This topic describes how to upgrade a deployment of Enterprise Insight to use a newer version of Semmle Core.
New versions of Semmle Core are released regularly. Each release contains improvements to the extractors used to build snapshot databases, the queries used to analyze snapshots and the queries used to load this data into an Enterprise Insight database. Many of these improvements are the direct result of customer feedback. To benefit from the improvements, you need to upgrade Enterprise Insight to use the new version of Semmle Core.
It is important that, before you upgrade Semmle Core on the machines that publish data to Enterprise Insight, you first upgrade the Insight server. This ensures that all data published to the Insight server can be processed correctly.
Before upgrading your system, you should back up:
Upgrade Semmle Core on the Insight server by following the standard upgrade instructions (Upgrading to a new version of Semmle Core).
If you are upgrading from 1.9.7, 1.9.8 or 1.9.9 you must upgrade all Enterprise Insight databases to the latest schema. If you are upgrading from an older version, you should discuss the upgrade with Semmle support.
There have been no changes to the Enterprise Insight database schema since version 1.10, so you do not need to perform a database upgrade if you are upgrading your Semmle installation from 1.10 or later. However, you must make sure to use the most recent version of Insight server after upgrading Semmle Core. The process for doing so is described below.
Perform the following steps for each Insight server that accepts connections over SSH.
odasa insightClient --stop <workspace-directory>
If you are upgrading from Semmle releases 1.9.7, 1.9.8 or 1.9.9 , perform the following steps:
datamodel
element of the Insight server configuration file. Open the Insight server configuration file (in the workspace directory of the Insight server service) and check the value of the datamodel
element. If it references the datamodel definition in the Semmle Core distribution, for example:<datamodel src="${semmle_dist}/templates/[team|enterprise]-insight/datamodel.xml" />
then the datamodel has already been updated when you upgraded Semmle Core in section 2 above. In this case you can continue with the next step.
However, if the value of the datamodel
element refers to a file in a different location, you will have to update that file to the new format introduced in release 1.12. If the file that is referred to is an unchanged copy of the Insight server configuration file that came with the previous Semmle Core distribution, replace that file with a copy of the new datamodel.xml
file, which you can find in the ${semmle_dist}/templates/[team|enterprise]-insight
directory.
If the referenced datamodel.xml
file has been customized, you must transfer the modifications to a copy of the new version of the file. In particular, each transaction
element now needs a name
attribute and a constraint
element as its first child element. For more information, see Scheduling database transactions.
If you are upgrading from release 1.10 or later, use the insightServer command to restart the SSH service for the Insight server:
odasa insightServer <
workspace-directory>
If you are upgrading from Semmle releases 1.9.7, 1.9.8 or 1.9.9, use the insightServer command with the --upgrade
flag to upgrade the database, using the information defined by the upgrade-directory
and databaseconfig
elements:
odasa insightServer --upgrade <
workspace-directory>
You can check the server.log
file stored in the log
subdirectory of the Insight server's workspace directory for details of the changes that were made.
Semmle recommends upgrading manually, using insightServer
command with the --upgrade
flag. However, if you would prefer upgrades to be run automatically, you can enable the autoupgrade feature described for HTTPS-based servers below.
Databases for HTTPS-based Insight servers are upgraded using the autoupgrade functionality introduced in release 1.9.10. The following process includes steps for enabling autograde if this has not previously been done:
Replace the insight-server.war
file in your Web Services container (for example, Tomcat) with the new version of this file in the $SEMMLE_DIST/tools
directory of the new release.
If you are upgrading from Semmle releases 1.9.7, 1.9.8 or 1.9.9—or if you did not enable autoupgrade in later releases:
datamodel
element of the Insight server configuration file. Open the Insight server configuration file (in the workspace directory of the Insight server service) and check the value of the datamodel
element. If it references the datamodel definition in the Semmle Core distribution, for example:<datamodel src="${semmle_dist}/templates/[team|enterprise]-insight/datamodel.xml" />
then the datamodel has already been updated when you upgraded Semmle Core in section 2 above. In this case you can continue with the next step.
However, if the value of the datamodel
element refers to a file in a different location, you will have to update that file to the new format introduced in release 1.12. If the file that is referred to is an unchanged copy of the Insight server configuration file that came with the previous Semmle Core distribution, replace that file with a copy of the new datamodel.xml
file, which you can find in the ${semmle_dist}/templates/[team|enterprise]-insight
directory.
If the referenced datamodel.xml
file has been customized, you must transfer the modifications to a copy of the new version of the file. In particular, each transaction
element now needs a name
attribute and a constraint
element as its first child element. For more information, see Scheduling database transactions.
Restart the Insight server.
Depending on your Java Web Services container, the Insight server might only be started once a client accesses that service. In this case you can use insightHttpClient
to upload an empty zip
file to trigger this process.
When the Insight server restarts, the upgrade-directory
is checked and any new upgrade steps are implemented during the startup process.
When you have upgraded the Insight server, you are ready to upgrade Semmle Core on the servers that publish data to the Insight server. You can upgrade Semmle Core on these servers by following the standard upgrade instructions (Upgrading to a new version of Semmle Core).
Open the template ei-client.xml file included in the odasa/templates/enterprise-insight
directory of the new version of Semmle Core. For each server that publishes data to the Insight server, check whether the ei-client.xml
files used by projects analyzed on that server need to be updated. For example, the update may include a new dashboard query. If so, update the file to include the new dashboard query.