Transitioning from Legacy MySQL 5.7

This procedure transfers selected SENSE configuration from a legacy MySQL 5.7 deployment to a new MySQL 9.7 deployment. It transfers configuration and profiles only. It is not a database migration or a disaster-recovery procedure. For the limits of system archives, see System Backup and Restore.

What Transfers

The exporter produces a system archive containing all three currently supported domains:

• System settings from the legacy rainsdb global_property table;
• Driver configurations and their properties from rainsdb; and
• Service profiles and profile ACL records from the legacy frontend and rainsdb schemas.

The archive does not contain service instances. See the limits section below.

Transfer Boundary

The exporter omits certain settings, such as those outside the known portable or environment namespaces, the internal project cache, and system.boot_strapped. Invalid driver or profile rows may be skipped with a warning.

Prerequisites

Before exporting:

1. Pull the latest source code or download the export-legacy-system-archive.py script from the repository.
2. Make sure the database is accessible from your shell. For docker containers you may need to attach the container to the overlay or bridge network.
3. Ensure the machine has Python 3 and the mysql CLI on PATH.
4. Prepare a secure destination for the archive. The exported JSON can contain sensitive system settings, driver credentials, and other secrets. Treat it as sensitive.

The script queries the legacy frontend and rainsdb schemas. It assumes the required legacy tables and fields exist; it does not preflight the source schema or provide a minimum-schema compatibility matrix.

A baseline legacy schema may lack the later-migration driver_instance.owner, locked, or restricted fields and the service_profile.favorited or tags fields. The exporter has no preflight or schema-version matrix; stop if the source does not provide the required fields.

Generate the Source Archive

Export the DB_PASS env variable and then execute the script via CLI. The exporter accepts the password only through DB_PASS and passes it to MySQL as MYSQL_PWD.

DB_HOST="<legacy-mysql-host>" DB_PORT="<mysql-port>" DB_USER="<mysql-user>" OUT="<secure-output-path>/legacy-system-archive.json" ./db/bin/export-legacy-system-archive.py

The script makes read queries and a session-scoped SET time_zone = '+00:00'; it does not perform source DDL or DML. It keeps query results in memory, uses a restrictive process umask, and writes JSON to a temporary file in OUT’s parent directory before os.replace atomically replaces the requested output on success. These behaviors do not replace secure handling of the final JSON.

Review the Export Result

The generated JSON may include export warnings, so you should inspect the nested settings, drivers, and profiles archives within the JSON. Then, reconcile expected source and archive record counts to make sure everything you expected to export is present.

Importing

There are two paths for importing the archive into a destination deployment: either via the SENSE Portal or API, or via the archive seeding feature.

SENSE Portal Import

Use this path when the destination deployment is already running, and you wish to import or restore the source archive into it. This allows you more flexibility in reviewing and applying the import but requires some additional steps and is not automated. For more information see System Backup and Restore.

First Boot

You may also choose to initialize an orchestrator using the archive seeding functionality, allowing a deployment to automatically import a provided archive bundle during its first startup. For more information see Initializing with an Archive.