SharePoint 2010 Upgrade: Test-SPContentDatabase – Key to Successful Upgrade

Posted on January 12, 2010 by Joel Oleson

One of the greatest enhancements to upgrade to SharePoint 2010 is the work that was done in PreUpgradeCheck and in the powershell commandlets of Test-SPContentDatabase and Upgrade-SPContentDatabase. Test-SPContent Database is very similar to the stsadm command PreUpgradeCheck, but it works with both 2007 and 2010. This command can be pointed at a database that isn’t part of the farm! That’s the coolest. If you want to see how a content database would fare in a given farm you can run the Test-SPContentDatabase command and get information on issues that would impact the farm you’re importing it into. Is the database compatible? Does it have all the assemblies installed, all the relevant features and solutions all set? Well run the commandlet to find out.

Many will be building new SharePoint 2010 farms and wanting to start clean from a hardware and software perspective. I do expect this to be the most common scenario. With just options of in-place upgrade or database attach, you’ll find this command to be the key. If you only run preupgradecheck (more resources below) on the farm you’re moving from, you’re missing important steps.

Preparing for Upgrade with Powershell

Test-SPContentDatabase

Test-SPContentDatabase -Name -WebApplication [-AssignmentCollection ] [-DatabaseCredentials ] [-ServerInstance ]

Test-SPContentDatabase –name SPContentDatabase –WebApplication http://test

Here’s an example of a sample Test-SPContentDatabase

In the example above, you can see examples of missing files, with a note to remedy by installing the missing feature with a path to the missing .dwp in this example. Also note that it shows if this will block the database attach upgrade. Pretty cool.

If you were to compare PreUpgradeCheck and Test-SPContentDatabase you’d see the output and reporting is very different, but they do compliment each other. For example with database attach at a minimum you should run them both. On your source you should be running preupgradecheck and in the destination you should be running test-spcontentdatabase.

Source (Your 2007 farm): PreUpgradeCheck will tell you what is broken or missing in the source.

Destination (Your Clean 2010 Farm): Test-SPContentDatabase will tell you what you’ve missed in setting up your 2010 farm.

There’s more information on TechNet on actually running the Test-SPContent database command. Here’s a couple of quotes on actual usage. Note, this is beta content and it may change. There’s some hidden gems of tips in these paragraphs below.

“Before you add the content databases to the Web applications, you can use a Windows PowerShell cmdlet to verify that you have all the custom components that you need for that database. At the command prompt, run the following cmdlet:

Test-SPContentDatabase –Name <database name> -WebApplication <URL>

[-ServerInstance <ServerInstanceName>] [-DatabaseCredentials <Domainusername>]

When you add the content databases, be sure that the root site for the Web application is included in the first content database that you add. In other words, before you continue, examine the root of the Web application in the original server farm to determine the first site collection. After you add the database that contains the root site, you can add the other content databases for the Web application in any order. You do not have to create any site collections to store the content before you add the database; this process creates the site collections for you. Be sure that you do not add any new site collections until you have restored all the content databases.

You must use the Stsadm command-line tool to add a content database to a Web application. Using the SharePoint Central Administration pages to attach a content database is not supported for upgrading.” emphasis added be me.

Database Attach with STSADM AddContentDb

“To add a content database to a Web application, you must use the addcontentdb operation.” (Emphasis added)

Simple:

stsadm -o addcontentdb -url <URL> -databasename <database name>

With Options:

stsadm.exe -o addcontentdb -url <URL name> [-assignnewdatabaseid] [-clearchangelog] -databasename <database name> [-databaseserver <database server name>] [-databaseuser <database username>] [-databasepassword <database password>] [-sitewarning <site warning count>] [-sitemax <site max count>]

If you are actually running a database attach upgrade please note that some of these options on the upgrade are added for specific reasons related to troubleshooting issues, such as clearing the change log and assigning a new database id because it’s already taken.

The powershell command Upgrade-SPContentDatabase can be used to resume a database attach failure. So you’d use the test-spcontentdatabase to check for missing, and use stsadm –o addcontentdb to add the content database, and use upgrade-spcontentdatabase to resume upgrades with issues.

After Infra Update each content database IDs are retained when you restore or reattach the database by using built-in tools. “Default change log retention behavior when using built-in tools is as follows:

The change logs for all databases are retained when you restore a farm.
The change log for a content database is retained when you reattach the database.
The change log for a content database is NOT retained when you restore just the content database.

Clearing the change log forces Search to run a full crawl on that database so that the index no longer references items that do not exist.”

Verify Status with Upgrade Logs and Upgrade Status Page

There are many places and ways you can check upgrade status. You can use the Upgrade Status page in Central Administration to check the status of upgrade on your site collections and then check the upgrade log, and run STSADM.

STSADM -o localupgradestatus (To see if any sites were missed or skipped for upgrade, be sure to run it on all WFEs.)
Upgrade Status page – From Central Administration, click Upgrade and Migration then Check upgrade status.
To open the upgrade and err log files – %COMMONPROGRAMFILES%Microsoft Sharedweb server extensions14LOGS. Note there are logs for each session.

Recap with Steps for 2007 to 2010 database attach upgrade based on the information in this post:

Of Course.. Acquire hardware, run lots of backups along the way, and build out the 2010 farm with all the best practices, run it all on a test environment, etc… Also note this is back of the napkin, obviously you need to add you own additional steps of communication, validation, and any other additional operational steps, etc…

1. Run PreUpgradeCheck on 2007 farm

2. Fix and address issues

3. Run PreUpgradeCheck to verify all issues addressed

4. Run Test-SpContentDatabase

5. Fix issues and make planning choices appropriately

6. Re-Rerun Test-SpContentDatabase

7. Upgrade the Service Apps and verify they are all good, then Run stsadm –o addcontentdatabase to add the relevant databases to the relevant web apps

8. Check the upgrade status both in central admin and in stsadm –o localupgradestatus on each SharePoint server and check the logs to verify the upgrade process itself was successful.

9. Re-Run Test-SPContentDatabase and verify database upgrade of sites was successful

10. Troubleshoot any issues then run Upgrade-SPContentDatabase if any databases need to resume upgrade

10. Visual verification

— Ready to start visual upgrade

Powershell Commands useful around Upgrade

Test-SpContentDatabase – discussed in this post

Upgrade-SPContentDatabase – to resume failed upgrades

Upgrade-SPEnterpriseSearchServiceApplication – Upgrade Search

Upgrade-SPSingleSignOnDatabase – Upgrade SSO

STSADM Commands useful around preparing for Upgrade

stsadm -o ExportIPFSAdminObjects

stsadm -o MergeContentDB