Upgrading the Senzing Entity Resolution Configuration to v4

This article is for general guidance. Always test any updates and changes in a non-production system before implementing them in production! If you are unsure of any steps please contact Senzing Support . Support is 100% FREE!

When upgrading from Senzing v3 to Senzing v4, there are changes to the Senzing Entity Resolution [ER] configuration. The configuration in the database used by Senzing must be updated accordingly.

This is the second of two steps. Complete Upgrade Schema to v4 first.

Generate config upgrade script

The sz_configtool utility, available in bin/, performs the ER configuration upgrade. A Senzing v3 configuration is compatibility version 10; the v4 engine requires 11.

Upgrade the repository schema first.
Upgrading the ER configuration first saves successfully, but the engine will fail to initialize with SENZ7226 | Incompatible datastore schema version.

sz_configtool reads the repository location from the environment, so in most cases you can start the upgrade without specifying the ER configuration.

sz_configtool

The tool locates the repository from the first of these it finds:

  1. -c <INI file>, an explicit sz_engine_config.ini . Use when the engine configuration you want is not the one the environment already points at.
  2. SENZING_ENGINE_CONFIGURATION_JSON .
  3. SENZING_ROOT, set by a project’s setupEnv, which resolves to that project’s own sz_engine_config.ini .

sz_configtool detects the older configuration and offers four choices:

Choice Action
U Upgrade. Applies the upgrade in memory; save persists it
V View. Prints the upgrade commands without applying them
E Export. Writes the upgrade commands to a file you name
C Cancel. Exits without touching the configuration

Choose V or E first to see what the upgrade will do, then run it again and choose U. U applies the upgrade in memory only; type save to persist it.

The commands come from the upgrade scripts (szcore-configuration-upgrade-<from>-to-<to>.gtc), read from <RESOURCEPATH>/config unless --upgrade-dir points somewhere else.

The sz_configupgrade utility, available in <project_path>/bin, is used to compute full Senzing engine configuration update scripts.

The <outputDirectory> must already exist

Example syntax:

sz_configupgrade -c <INI file> -o <outputDirectory>

Example syntax with example parameters:

sz_configupgrade -c ~/senzing/etc/sz_engine_config.ini -o ~/outputDir

This command generates the sz_configtool upgrade script file from the registered repository config version to the current Senzing v4 engine version.

sz_configupgrade -c ~/senzing/etc/sz_engine_config.ini -o ~/outputDir/sz-configuration-upgrade.gtc

Precautions

Neither U nor --accept-upgrade writes to the repository. Both apply the upgrade in memory only. save is what persists it, and sz_configtool can perform the configuration update itself by combining the two, for example --accept-upgrade -f -C save.

Applying the upgrade directly is not recommended in production. Use V or E to view or export the upgrade commands first, and review them with your team to gauge the specific operational impact any changes might have.

sz_configupgrade can perform the configuration update itself with the -a argument and no -o argument.

Applying the upgrade directly is not recommended in production. Create the scripts first and review them with your team to gauge the specific operational impact any changes might have.

Verifying the upgrade

After saving, the configuration is registered at compatibility version 11 and a new default configuration ID is set. sz_configtool starts without prompting for an upgrade, which confirms the configuration matches the engine build.

If you have any questions, contact Senzing Support. Support is 100% FREE!