> For the complete documentation index, see [llms.txt](https://docs.workflowgen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.workflowgen.com/upgrade/10.5.0/workflowgen-upgrade/migrating-a-workflowgen-v8-or-v9-sql-server-database-to-v10.md). # Migrating a WorkflowGen v8 or v9 SQL Server Database to v10 ## When to use this guide Use `migrate-v8-v9-to-v10.ps1` from the target WorkflowGen package to update an existing supported v8 or v9 database. It selects the missing migrations, applies them in order and validates the resulting schema. You don't need Git access, loose v8 or v9 SQL files or a separate v9 installation before running it. ## Source version compatibility and migration requirements ### Supported source versions and validation The supplied manifest records validated source **versions 8.0.0 through 8.6.0** and **versions 9.0.0 through 9.7.0**. Use the installed WorkflowGen application version, including its patch number; the database schema alone cannot identify every patch release. The runner checks that the schema matches the declared version. Do not enter a different version to bypass a refusal. A newer v8 or v9 release is not rejected solely for exceeding those ranges. The runner warns and asks for explicit consent to assess it against the latest known schema profile of the same major version. It then checks the source schema and application registrations, plus additional column, constraint and trigger compatibility checks, before creating a migration journal or changing data. A failed check always stops the migration; confirmation cannot override it. Other major versions are not eligible for this path. For unattended use, `-AllowUnvalidatedSourceVersion` supplies this consent. Use it for both preview and apply (and resume if needed), with the **actual** installed version. `-Confirm:$false` alone does not consent to an unvalidated source. The preview reports `SourceValidation` and `SchemaProfileVersion` so you can distinguish a validated release from a newer release assessed against a known profile. Keep the same source version and package when resuming. ### Compatibility checks and precautions These checks establish compatibility with the packaged migration contract, not support for every possible future application or data change. Rehearse on a restored backup first. Unrecognized schema customizations may require an updated package or investigation; do not remove constraints to force acceptance. ### Migration target and scope The current package and migration target is **10.5.0**. The last SQL schema update remains **10.4.0**: 10.5.0 introduces no additional database update. A later package may declare a different target or source range: always use its own files and review the target returned by the preview. This tool does not upgrade application files, configuration, forms or services; move the database to another server; install SQL Server components; or index existing requests. New installations use creation scripts. Existing v10 installations use the normal incremental v10 update scripts instead. ## Before you start * Rehearse the procedure on a restored backup containing your representative data and customizations before upgrading the live environment. * Use SQL Server 2016 or later with Full-Text Search installed. If moving to a newer engine, complete that move first. Native vector support is not required for full text operation. * Use Windows PowerShell 5.1 or PowerShell 7 on Windows, with access to the target database. The examples use Windows integrated authentication. * For preview, the database user needs metadata visibility and read access to the tables inspected by validation, including application registrations. Its default schema must be `dbo`. Applying the migration requires membership in `db_owner`; the target must be a writable user database. * Keep these files from the **same package** together, without editing them: ``` migrate-v8-v9-to-v10.ps1 legacy-migration-manifest.json migrations/ legacy-migration-bundle.json validate-migration-schema.sql validate-newer-source.sql ``` ## Migration procedure #### Step 1: Preview the migration Open PowerShell in the package's `Databases\MsSQLServer` folder. Replace the server, database, and source version in this example with your own values: ```powershell $connectionString = 'Server=SQL_SERVER;Database=WFGEN;Integrated Security=True' $sourceVersion = '9.7.0' $plan = .\migrate-v8-v9-to-v10.ps1 -ConnectionString $connectionString -SourceVersion $sourceVersion $plan | Select-Object Status, Server, Database, SourceVersion, SchemaProfileVersion, SourceValidation, TargetVersion $plan.Steps | Format-Table Id, File, Status ``` Without `-Apply`, the runner connects and checks prerequisites but makes no persistent database changes. A new migration returns `Status = Planned`. Confirm the server, database, source version, target and selected steps before continuing. A preview failure must be resolved before applying the migration. You can also request PowerShell's built-in help: ```powershell Get-Help .\migrate-v8-v9-to-v10.ps1 -Full ``` #### Step 2: Back up and apply Arrange a maintenance window. Stop WorkflowGen application pools and services on every application node using this database, and stop any other writers. Take matching database and application backups and confirm your restore procedure before proceeding. Keep the services stopped until both database and application upgrade work is complete. Using the same connection and source version, apply the migration: ```powershell $result = .\migrate-v8-v9-to-v10.ps1 -ConnectionString $connectionString -SourceVersion $sourceVersion -Apply $result | Select-Object Status, Server, Database, SourceVersion, TargetVersion $result.Steps | Format-Table Id, File, Status ``` Successful execution returns `Status = Completed` after target validation. Do not manually replay the SQL files included in the bundle afterward. A repeat invocation using the same package and original source version validates the completed target and returns `AlreadyCompleted`. The runner preserves customer workflow data and supported custom registrations. Historical updates can intentionally change built-in application descriptions, class names and default or required flags. Review customizations during the rehearsal; an incompatible or partially upgraded schema may be rejected. #### Step 3: Complete the application upgrade and verify Deploy the matching v10 application files, then reconcile configuration and customizations using your application upgrade procedure. Restart the application pools and services only once that work is complete. Check sign-in, existing requests, process execution, and the searches your users reply on. Enable chunk indexing for the data you want to search and apply those settings to existing requests where required. Allow the Engine Service and full-text indexing to finish before checking search results. On a database without native vectors, full-text search needs no embedding API key. On a native-vector database, semantic search also needs a configured embedding provider. If the engine was upgraded but an existing compatibility column remains, follow the separate [vector activation instructions](/upgrade/10.5.0/optional.md#activate-vector-storage-after-an-engine-upgrade). ### If the execution fails or is interrupted Keep the application stopped. Record the reported step and error, retain the original package, and resolve the cause with your database administrator or support contact. The complete migration is **not one transaction**: earlier successful steps remain committed. Ordinary migration files and their journal records are transactional; full-text operations have separate recovery checks. When an interrupted migration journal exists, resume using the **exact same package and original source version**: ```powershell .\migrate-v8-v9-to-v10.ps1 -ConnectionString $connectionString -SourceVersion $sourceVersion -Apply -Resume ``` If failure occurred before a journal was created, correct the problem and run preview and `-Apply` again without `-Resume`. Package hashes guard against resuming with changed SQL or code. Never edit the migration journal or bundle to skip a failed step.
Refusal or errorNext action
Unsupported source version or schema mismatchVerify the installed version, package and restored schema; do not guess a version.
Full-Text Search unavailableInstall or enable the required server component before retrying.
Permissions or default schemaHave the administrator provide the required access and dbo default schema.
Duplicate application or parameter registrationsReview the conflicting records with the administrator; do not delete customer data blindly.
Application parameter conflict or source milestone mismatchVerify the declared version and compare the named application's registration with the standard registration for that version. Reconcile intentional customizations with support before retrying preview.
Another migration is runningWait for the existing run and inspect its result before retrying.
Package or journal mismatchRecover the original package and source version; do not alter checksums or journal rows.
Command timeoutInvestigate server load or blocking; use -CommandTimeout (seconds) if an appropriately longer timeout is needed.
There's no automatic downgrade. To abandon a partially completed upgrade, restore the matching database and application backups before restarting the previous application version. ### Built-in application parameter conflicts WorkflowGen supplies and controls the parameters of built-in applications such as OPENAICHAT. An altered registration can occupy a number required by a standard parameter while omitting its expected name. The migration runner rejects this condition in source preflight, before creating a migration journal or applying SQL updates; preview and `-Apply` both perform that check. This is a refusal for an altered source, not a required repair for normal installations. Do not delete or renumber parameters blindly. Compare the named registration against the correct released version, check dependent mappings with support, and rehearse any agreed repair on a restored copy before retrying. Executing loose SQL updates manually bypasses the runner's preflight. In that route, a conflicting number can cause a primary-key error after earlier batches have committed. Stop and assess the partial state; neither replaying the whole file nor using the runner's `-Resume` without its journal repairs that state. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.workflowgen.com/upgrade/10.5.0/workflowgen-upgrade/migrating-a-workflowgen-v8-or-v9-sql-server-database-to-v10.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.