Upgrade Configuration
The following is a reference of all the additional configuration settings that can be used in the context of an upgrade.
The format here follows that in the main configuration setting reference.
UpgradeConnectionInformation Settings
SourceDataPersistenceEngine (upgrade)
A string (`sqlserver`, `mysql`, `postgresql`, or `oracle`) corresponding to the DBMS flavor in use for the source database.
SourceSystemDatabaseConnectionString (upgrade)
The connection string to use when connecting to the system schema on the source database.
SourceTenantDatabaseConnectionString (upgrade)
The connection string to use when connecting to the tenant schema on the source database.
SourceDatabaseSchema (upgrade)
The DBMS-level schema to use when connecting to the source database. At this moment, it is not possible to specify different tenant and system DBMS schemas.
SourceDataHelperAssemblyName (upgrade)
The assembly containing the custom data helper class for the Engine instance. Used only in .NET.
SourceDataHelperClassName (upgrade)
The fully-qualified name of the class to be used as the Data Helper for the source database.
TargetDataPersistenceEngine (upgrade)
A string (`sqlserver`, `mysql`, `postgresql`, or `oracle`) corresponding to the DBMS flavor in use for the target database.
TargetSystemDatabaseConnectionString (upgrade)
The connection string to use when connecting to the system schema on the target database.
TargetTenantDatabaseConnectionString (upgrade)
The connection string to use when connecting to the tenant schema on the target database.
TargetDatabaseSchema (upgrade)
The DBMS-level schema to use when connecting to the target database. At this moment, it is not possible to specify different tenant and system DBMS schemas.
TargetDataHelperAssemblyName (upgrade)
The assembly containing the custom data helper class for the Engine instance. Used only in .NET.
TargetDataHelperClassName (upgrade)
The fully-qualified name of the class to be used as the Data Helper for the target database.
UpgradeTenancy Settings
If given, use this tenant's ID anytime we need to determine the value of an engine_tenant_id column. For single-tenant single-database customers (most customers), the recommended value of this setting is 'default'. For multi-tenant multi-database customers, this should be the name of the tenant associated with the database you are currently upgrading. For multi-tenant single-database customers, this setting should be omitted or left blank.
PackageToTenantQuery (upgrade, default: SELECT app_id FROM SCHEMA_PREFIX.ScormPackage WHERE scorm_package_id = @scorm_package_id)
For multi-tenant upgrades, this setting allows the user to specify a query that takes a scorm_package_id as input and returns the name of the associated tenant as output. This setting is required for multi-tenant upgrades.
TenantIdCacheSize (upgrade, default: 1000000)
For multi-tenant upgrades, this setting affects the size of the cache used to map various kinds of internal Engine database IDs to tenants. Keep in mind that there are four such caches that will use this setting!
ZeroTenantOverride (upgrade, default: default)
This setting allows the user to specify what name the 'zero' tenant has. This will go on to determine what the default value of their external configuration's tenant name parameter will be post-upgrade.
UpgradeSystemTables (upgrade, default: true)
This setting can be disabled in order to skip upgrading the system tables. A system connection string will still need to be provided when upgrading tenant tables.
UpgradeTenantTables (upgrade, default: true)
This setting can be disabled in order to skip upgrading the tenant tables. A system connection string will still need to be provided when upgrading tenant tables.
UpgradePerformance Settings
BatchSize (upgrade, default: 500)
The number of rows to process in a single batch.
A mapping of phase names to batch sizes which will override the BatchSize setting, for situations where different phases call for different batch sizes.
MaxProcessingQueueSize (upgrade, default: 3)
The maximum number of batches that can be queued up at once.
ThreadCountOverrides (upgrade)
A mapping of worker names to thread counts to allocate a given number of threads for a specific worker.
ThreadCountMultiplier (upgrade, default: 1)
A multiplier that will be applied to the configured thread counts. This allows customers to increase the number of active threads easily while maintaining the default proportions.
DatabaseReadThreads (upgrade, default: 2)
The number of threads available for workers that read from the database. This does not affect the number of threads devoted to getting the rows into the batch pipeline in the first place, which is always a single-threaded operation.
ProcessingThreads (upgrade, default: 1)
The number of threads available for workers that process data in memory. Since I/O is not involved in these threads, the benefit from multi-threading is presumably small.
DatabaseWriteThreads (upgrade, default: 4)
The number of threads available for workers that write to the database.
FilesystemThreads (upgrade, default: 2)
The number of threads available for workers that access the filesystem.
OnlineIndexingSupported (upgrade, default: true)
Stipulates whether the CREATE INDEX statements used during phase 1 of an online upgrade can be used without locking the table. This setting is not checked for PostgreSQL. For technical reasons we can't do lock-free indexing on PostgreSQL. This setting should only be marked false if you are running a non-Enterprise Edition of Oracle/SQL Server.
If given, only copy rows after this date.
UpgradeCloud Settings
The secret key used for AWS API access to S3.
The secret id used for AWS API access to S3.
The name of the S3 bucket used for object storage.
The name of the AWS region the S3 bucket is located in.
FailOnMissingXapiStatements (upgrade, default: true)
If enabled (default), the upgrade will raise an error and fail in the event that the upgrade requests certain statements from the object store and doesn't find them. If disabled, there will simply be a warning instead.
CleanUpFileStore (upgrade, default: true)
If enabled (default), the upgrade will move objects in the document store. If disabled, the upgrade will copy those objects instead.
SkipXapiSandboxes (upgrade, default: true)
If enabled (default), the upgrade will ignore any rows associated with an xAPI sandbox. If disabled, the upgrade will copy sandboxed data.
DropObsoleteTables (upgrade, default: true)
If enabled (default), 'obsolete' tables (tables that the upgrade tool recognizes as having belonged in a prior version of Enging but are no longer included in the current schema) will be dropped. If disabled, these tables will be left alone.
Schema Settings
DropExternalForeignKeys (upgrade)
If false (default), the upgrade will fail upon encountering foreign keys that involve an Engine table and a customer's table. If true, the upgrade will instead issue a warning and then drop those foreign keys. It will not add the foreign key back at the end of the upgrade.
ExternalPackageKeyColumns (upgrade)
Allows a customer to explicitly specify the definitions of external package key columns on ScormPackage. If used, the columns must match with the properties of the integration layer's implementation of ExternalPackageId.
ExternalRegistrationKeyColumns (upgrade)
Allows a customer to explicitly specify the definitions of external registration key columns on ScormRegistration. If used, the columns must match with the properties of the integration layer's implementation of ExternalRegistrationId.
A comma-delimited list of column specifications for columns the customer added to ScormPackage, but are NOT part of the external key.
ExtraRegistrationColumns (upgrade)
A comma-delimited list of column specifications for columns the customer added to ScormRegistration, but are NOT part of the external key.
IncludeApiIntegration (upgrade)
This setting is often set automatically, but can sometimes be set manually. If given, tells the upgrade tool that it should include the Engine API-related columns.
IntegrationToApiRegistrationIdQuery (upgrade)
This setting must be provided for customers that are migrating from an integration layer to our API integration. This query returns a string that will be used as the registrations' IDs when communicating with the API. The customer's current integration columns will be passed in as parameters.
IntegrationToApiCourseIdQuery (upgrade)
This setting must be provided for customers that are migrating from an integration layer to our API integration. This query returns a string that will be used as this packages' IDs when communicating with the API. The customer's current integration columns will be passed in as parameters.
RegistrationToApiLearnerQuery (upgrade)
This setting must be provided for customers that are migrating from an integration layer to our API integration. Given a row from ScormRegistration (which will contain any integration layer-defined columns), the query must return a learner_id (which must be a unique varchar), learner_first_name, and learner_last_name for the learner associated with that registration.
Migration Settings
If enabled, drops and recreates all xAPI-related tables instead of upgrading them.
If enabled, drops the ScormLaunchHistory table and recreates it instead of upgrading it. This table generally has a lot of data, and therefore this can result in significant time savings for the upgrade.
SkipxAPIFileStoreMigrations (upgrade)
If enabled, skips any migration or phase related to xAPI File Store.
A comma-delimited list of phases that the upgrade should skip entirely. Ask Rustici Support for the name of particular steps you want to skip.
MigrateLwsPostbackConfig (upgrade)
If enabled for an LWS upgrade, upgrades the postback configuration for each registration to the new configuration schema.
Deduplication Settings
DeduplicateExternalKeysMode (upgrade, default: ERROR)
The external key deduplication mode to use. Using this setting may result in lost data, so be warned! Recommended values are DELETE or REASSIGN.
MaxCasualtiesPerDuplicate (upgrade, default: 5)
When deduplicating external keys, imposes an upper limit on the number of duplicates that can be reassigned. If the limit is exceeded, the upgrade stops in error. If you are having problems, the limit can be raised, but be sure to clear this with the support team first.
ScormPackageDeduplicationQuery (upgrade)
If DeduplicateExternalKeys is enabled, this query will be run for each duplicated package row. Contact the Engine support team if you wish to use this setting.
ScormRegistrationDeduplicationQuery (upgrade)
If DeduplicateExternalKeys is enabled, this query will be run for each duplicated registration row. Contact the Engine support team if you wish to use this setting.
ScormPackageDeduplicationIndex (upgrade)
The index to use for deduplication, if different from the index we are upgrading to. Required when external key columns are removed or renamed.
ScormRegistrationDeduplicationIndex (upgrade)
The index to use for deduplication, if different from the index we are upgrading to. Required when external key columns are removed or renamed.
Debug Settings
AsynchronousEnabled (upgrade, default: true)
If disabled, runs the upgrade in synchronous mode. Occasionally useful for debugging at the cost of performance.
If set, the row count audit will be skipped altogether. This is used when the row count audit would take too much time for the designated cutover window in phase 3. Use with caution, and preferably only after running a test cutover with the row count audit enabled first. Overrides IgnoreRowCountAudit.
If set, row count audit errors becaome warnings and the upgrade will proceed past a failed row count audit. This is intended for when the row count audit is expected to fail, but the information may still be valuable
OrphanRowThreshold (upgrade, default: 0.0078125)
The upgrade checks for foreign key violations. If it finds a number of orphaned rows on a table that expressed proportionally to the number of rows in the table is larger than this threshold, the upgrade will stop and raise an error. The default is 1 row out of every 128.
This setting set automatically during phased upgrades. This setting can be set to true during an all-in-one upgrade to make it behave like a phased upgrade (in that it will aggressively choose row-copying over alter table), which can be useful for testing.
LimitRowsByStartTime (upgrade)
This setting is set automatically for phased upgrades (though not necessarily always to true). This setting can be set to true during an all-in-one upgrade to enable this feature in that upgrade type as well, which is useful for testing.
AllowUnrecognizedSettings (upgrade)
If false (default), raises an error and stops the upgrade if there is something in the configuration setting store that we don't recognize. If true, issue a warning instead.
SaveProgressIntervalSeconds (upgrade, default: 120)
Progress will be saved during row copy at an periodic interval defined by this setting, as well as whenever the upgrade switches to a different table.
SkipPreTransformationRowCount (upgrade)
If enabled, do not count the number of rows before performing ALTER TABLE operations.
SkipOrphanRowCleanup (upgrade)
If enabled, do not look for orphan rows before trying to add foreign keys.
UpsertUsingExternalKeys (upgrade)
If enabled, when row-copying data to ScormPackage and ScormRegistration, use the external key columns as the keys when matching upserts instead of the primary key. This is meant to cover the rare situation where packages and registrations are deleted and recreated with the same external key while the row copy upgrade is in progress.
When given, this tag is appended to all progress tracking IDs, so multi-DB upgrades won't share state when run in parallel.
A list of tables to transform using 'CREATE TABLE AS SELECT' statements instead of ALTER TABLE statements. Set to '*' for all tables.
LwsEnabled (upgrade, default: true)
If enabled and LWS tables are detected, enables LWS-specific upgrade migrations.