Upgrade to Subscription Edition by database attach

Moving SharePoint Server 2016 or 2019 to Subscription Edition is not a copy and not an in-place upgrade. Microsoft supports one method: a new farm, the content and service application databases copied to it, and each database upgraded as it is attached. What decides whether that works is almost entirely what was done to the new farm before the first content database reached it.

What has to be true on the new farm before a content database is attached, and how do you prove the attach worked?

The decision this chapter leads to is a go or no-go per content database: attach it now, or not yet, and why.

Which farms this chapter is for

A farm on SharePoint Server 2016 or 2019: Microsoft supports upgrading those two by database attach, and an earlier farm must first reach one of them (overview of the upgrade process, checked on 1 November 2026). In Microsoft's words, "you upgrade only the content for your environment and not the configuration settings" (upgrade content databases, checked on 1 November 2026).

A move into SharePoint Online is a copy, not an attach, and follows Chapters 8 and 9.

What travels in the database, and what does not

Sources for the table: upgrade content databases and upgrade service applications, both checked on 1 November 2026.

The right column is the work. Microsoft names a new environment that is missing the customised features, solutions or other elements as one frequent cause of failures during upgrade, which is why the column is finished before the first attach rather than after it.

Work in the order Microsoft documents

Microsoft documents four phases: build the new farm, copy the databases to it, upgrade the service applications, then upgrade the content. Web applications belong to the last phase: "for upgrade, you create web applications later in the process, after you upgrade the service application databases" (create the farm for a database attach upgrade, checked on 2 November 2026). So do the customisations. Microsoft gives no reason they could not go in earlier, and this chapter follows the documented order.

Build the farm, and nothing on it yet

Windows Server 2019, 2022 or 2025, .NET Framework 4.8, and SQL Server for Windows in a version "that supports database compatibility level 150": SQL Server 2019 CU5 or later, or 2022 or later (requirements for SharePoint servers and for database servers, checked on 2 November 2026). Install a current public update first: each one is supported for a year from its release (servicing policy, checked on 2 November 2026).

Create no web application yet, and do not let the Farm Configuration Wizard create the service applications you will upgrade. Where 2013 workflows will run, install SharePoint Workflow Manager; Microsoft's update notes from August to October 2026 say its update KB5002799 goes in "before you install this cumulative update", and that a farm still on the classic Microsoft Workflow Manager must set server debug flag 53601 to keep using it (October 2026 notes, checked on 2 November 2026).

Copy the databases

Set the 2016 or 2019 databases to read-only, so that "users can continue to view content" but cannot change it, leaving the search databases writable for now. Back them up, restore them on the new SQL Server, and set them back to read-write there: "You cannot upgrade a database that is set to read-only." Keep the original backups in reserve (copy databases to the new farm, checked on 2 November 2026). A restored database keeps its old compatibility level (ALTER DATABASE), and Microsoft gives 150 for Subscription Edition content databases (supported levels, both checked on 2 November 2026), so check it after each restore.

Bring the service applications across

Create each upgradable service application from its copied database, and create Word Automation and Machine Translation new. Where 2013 workflows move, one more database goes with them: "You must move the App Management database along with the content, WFM, and Service Bus databases. If you don't, all workflows created before the migration will fail." The same page says this can be corrected later, and is easier avoided (SharePoint Workflow Manager on a new farm, checked on 2 November 2026).

Recreate the web applications and the customisations

Each web application keeps its URL: with a different one, "Office applications might not be redirected correctly to the new URLs and all bookmarks to the old URLs will not work". Authentication may not stay as it was: classic mode was removed for content web applications, which "only support claims authentication mode", and Basic authentication has been unsupported since 14 July 2026 (what is deprecated or removed, checked on 2 November 2026). Convert-SPWebApplication converts to Windows claims, and converts a user only "if the source account is enabled and queryable" (Convert-SPWebApplication, checked on 2 November 2026). Microsoft's Subscription Edition pages do not say on which farm to convert; rehearse it on copies.

Then install every customisation the table lists (upgrade content databases, checked on 2 November 2026), found on the old farm, where stsadm -o enumallwebs still exists. Each farm solution is kept, adapted, replaced or eliminated, as Chapter 15 sets out, and elevated code is reviewed first, as Chapter 17 does.

Test, then attach

Test each content database against the web application that will host it:

Test-SPContentDatabase -Name <DatabaseName> -WebApplication <URL>

The cmdlet checks that every customisation the database references is installed. It changes nothing, but it can load the database, so run it on one nobody is using (Test-SPContentDatabase, checked on 2 November 2026). Each missing component it names is installed, or recorded as a decision to do without it.

Then attach, with PowerShell; Central Administration does not support attaching for upgrade:

Mount-SPContentDatabase -Name <DatabaseName> -DatabaseServer <ServerName> -WebApplication <URL>

Attach the database with the web application's root site collection first, and the My Site host before the My Sites. Parallel attaches should start several minutes apart, because of temporary locks on the web application (upgrade content databases, checked on 2 November 2026).

Prove the attach worked before anyone uses it

Three readings, for every database:

Get-SPContentDatabase | ft Name, NeedsUpgradeIncludeChildren

• The Upgrade Status page in Central Administration lists the session that attached it as succeeded, with its errors and warnings counted.
• NeedsUpgradeIncludeChildren is false.
• The upgrade error log under %COMMONPROGRAMFILES%\Microsoft Shared\web server extensions\16\LOGS has no error, and every warning in its summary is read and recorded.

A clean log proves the database was upgraded, not that the business works. The functional checks follow: sites opened by a user of each authentication method, each kept customisation exercised, each elevated operation called by a user who may and one who may not, 2013 workflows run to completion, and a full crawl that returns only what each user may open. We recommend writing them down, with their evidence, before the first attach.

Rollback is the read-only source and the reserved backups, and it is clean only while nobody has written on the new farm. Chapter 9 sets out what each state after that means.

Out of scope

This chapter assumes Subscription Edition was chosen and the customisations inventoried. It does not design the farm's topology or MinRole layout, cover Project Server, or evaluate third-party migration tools; the cutover decision is Chapter 9. The Subscription Edition migration pack generates the inventories, tasks, tests and runbook for this sequence from a description of the farm.

Before you continue

• Every content database comes from 2016 or 2019, and the four phases run in Microsoft's order
• The farm runs a current update, with KB5002799 first where SharePoint Workflow Manager runs
• The databases are restored read-write, their compatibility level checked, the source and backups kept
• The service applications are upgraded or created new, App Management moved with 2013 workflows
• Web applications keep their URLs in claims mode, Test-SPContentDatabase findings are resolved, the attach order is written
• Upgrade status, NeedsUpgradeIncludeChildren and the log are recorded per database, with the functional checks' evidence

Download chapter 23 (PDF)Same text, same tables, same sources as this page.