Frequently Asked Questions (FAQ)–Pre-upgrade tool of TFS 2015
With Release of Team Foundation Server 2015, we have released the pre-upgrade tool to cut down on upgrade time for really large collections.
Please go through the documentation for the tool here.
I have compiled a few FAQ, which you may have regarding this tool.
What is the Pre Upgrade tool?
Pre-upgrade tool will help in doing major upgrade work while you are still at TFS 2013 (QU4/5) and still in production. Its sole purpose is to cut down on the upgrade time.
On what version of TFS can I use the pre-upgrade tool?
Pre-Upgrade tool can only be run against TFS 2013 Update 4 or TFS 2013 Update 5.
What’s the SQL requirement?
SQL Server 2012 SP1 (or greater) or SQL Server 2014 CU3 (or greater). Also, it can only be run if you are using Enterprise edition of SQL Server.
What permission do I need to run the tool?
We need SQL SysAdmin (no TFS permission is required).
How do we run the tool?
The recommended procedure for running TfsPreUpgrade.exe is:
- Download TfsPreUpgrade.exe. Note that the machine on which you install TfsPreUpgrade is not important so long as it can access the relevant SQL instance(s) - it comes zipped up with all of its dependencies.
- Unzip it to a local directory.
- Determine which collection databases you wish to run TfsPreUpgrade.exe on. It can be run on any collection databases without negative impacts on their upgrade-ability, but is generally only needed on databases that are large enough to require significant downtime during an offline upgrade. Microsoft recommends using TfsPreUpgrade.exe on databases above 1 TB in size.
- As a user who is a sysadmin on the SQL instance (TfsPreUpgrade sets several traceflags during its execution), execute the Run command:
TfsPreUpgrade.exe Run /TargetDatabaseNames:"{SQL Instance};{Collection Database Name}"
- If you wish to run TfsPreUpgrade.exe on more than one collection database, you can either use multiple invocations of TfsPreUpgrade.exe (in which case they will run in parallel) or you can specify multiple comma-separated SQL instance / Collection Database strings in a single invocation (in which case they will run sequentially).
What does the tool actually do?
- Enable compression for a small number of tables that were not compressed in 2013 but will be in 2015.
- Scan for and fix a very rare but well understood data corruption in TFS version control data.
- Create new tables and migrate existing data to them.
- Create triggers.
- Update stored procedures.
- Create indexes. (Enterprise editions of SQL Server are required in order to allow these operations to be performed online.)
How much space would I require?
TfsPreUpgrade.exe can provide an estimate of how much space it will attempt to pre-allocate by running the Estimate command.
TfsPreUpgrade.exe Estimate /TargetDatabaseNames:"{SQL Instance};{Collection Database Name}"
Any operation which I should avoid while the tool is running?
TFVC operations that deal with very large numbers of items are the most likely to be negatively impacted by the triggers that TfsPreUpgrade.exe creates. If you can, avoid these TFVC operations while TfsPreUpgrade.exe is running and before offline upgrade to TFS 2015 is completed.
- Creating, deleting and renaming branches.
- Destroy operations which impact large numbers of items.
- Deleting team projects that use TFVC.
If you do need to perform these operations, you can expect them to take at least twice as long to complete with the TfsPreUpgrade triggers in place.
Can I run it on selected Collection?
Yes, tool is supposed to be run on collection. If you have multiple collections then you can either run it one after another or have multiple instance of tool running.
Can I use our TFS server for day to day work while tool is running?
Yes, TfsPreUpgrade.exe works by creating new copies of the tables most impacted by the schema changes present in TFS 2015 and then migrating data from the original tables to the new copies. In order to handle ongoing user activity, it also puts triggers in place that keep changes to the original tables flowing to the new copies.
Should I run it against all collections?
We recommend tool to be run when collection is really large (>100s of GB). If you have a collection which is really big then run it against that collection and you can skip for other smaller collections.
Will it impact performance of my Server?
Microsoft has optimized TfsPreUpgrade.exe extensively in order to minimize its performance impacts on your servers and users, but it can and will have an impact on performance.
Will I be able to do all TFS functions while tool it running?
There are few things which tool blocks, below are list of those operation.
Blocked operations
Early on during the execution of TfsPreUpgrade.exe a number of "safety" triggers are put in place to block operations which were allowed by TFS 2013 but which are either no longer allowed by TFS 2015 or which would cause problems in the presence of the triggers put in place by TfsPreUpgrade.exe. These include:
1.Deletion of team projects. It is not recommended to delete team projects once you have run TfsPreUpgrade.exe against a collection database. If you do delete a team project, it will fail just before finalizing the deletion, leaving the project behind in a Deleting state. Team project deletion will be supported again once you upgrade to TFS 2015.
2.Creation of workspaces with references to root folders which do not exist. These will fail with error TF10169. Note that one scenario where this could surface is in build definitions whose workspace templates reference root folders which do not exist - in these scenarios, builds may fail during workspace creation with the given error. This scenario will continue to be unsupported in TFS 2015 due to changes related to Team Project rename but will fail with a more relevant error message.
3.Calling VersionControlServer.CreateTeamProjectFolder() via code written against the TFS client OM. This will fail with error TF10169. This scenario will continue to be unsupported in TFS 2015 due to changes related to Team Project rename but will fail with a more relevant error message.
Because of Pre Upgrade tool my server is very slow, Can I cancel the tool?
We can run TfsPreUpgrade.exe Revert command to cancel the tool.
Will the revert command put me back where I started?
Running TfsPreUpgrade.exe Run has a number of side effects which are not reverted by runningTfsPreUpgrade.exe Revert. Of most interest, any pre-allocation of database and/or transaction log space done by TfsPreUpgrade.exe will not be reverted, meaning that your database files may be significantly larger than they were prior to running TfsPreUpgrade.exe. The extra space will be unused, however, since the additional tables created by TfsPreUpgrade.exe will be deleted. We recommend leaving this space in place, both since it will naturally be filled in as the size of the data in your database files goes up, and because it will be needed eventually by the upgrade to TFS 2015.
The other side effects which are not reverted are not impactful and are listed here only for your information. These changes would have been made by an upgrade to TFS 2015 in any case, and should not have any impact on the functioning of your server or on its eventual upgrade.
1. Any corruptions found and fixed in TFS version control data will not be reverted.
2. A column added to tbl_Version by the corruption detection and fixup script will not be removed.
3. Tables for which compression is enabled will not have it disabled again.
Something happened while running the tool and it got cancel what should I do next?
TfsPreUpgrade.exe is written so that canceling it cancels the operations it is performing. It should never leave your database in a bad state, and can always be re-run multiple times if it exits before it has run to completion.
If upgrade tool run successfully, does it mean I would not see any issue during final upgrade.
Pre-Upgrade only do a partial upgrade, it does not replace a test upgrade which you might want to do to test upgrade process. You may still see issue with upgrade ever after running pre upgrade tool. We would recommend running a test upgrade.
Can I run preupgrade.exe on a collection which is in detached state?
Yes you can, but it would defeat the main purpose of the tool as it’s supposed to be run against a working collection to save time.
Hope this helps!
Content By : Romit Gulati
Comments
Anonymous
September 11, 2015
In pre-reqs for tfs, you mention tfs 2014 update 5. huh? did you mean tfs 2012 update 5? thanks!Anonymous
September 15, 2015
Thanks for pointing that out. It's TFS 2013 Update 5 :)Anonymous
July 12, 2016
Pre-upgrade tool only working for 2013.5 I can understand. What I cannot understand is why it does not work for the Standard version of SQL since that is the only version Microsoft allows you to run it, with unless you want to by another SQL Enterprise license. So I can estimate all my proof of concept VMs and our test environment because they run the developer edition of SQL, but not our production environment... not too impressed.- Anonymous
July 20, 2016
Hello Tad,One of the things that the pre-upgrade tool does is that it enables compression for a small number of tables that were not compressed in 2013 but will be in 2015.Since compression is an enterprise SQL only feature, and the pre-upgrade tool is targeted for huge databases, it has become a requirement.
- Anonymous