January 1, 2022

How to Plan a Successful Tableau Server Upgrade

By Aidan Bramel

For Tableau Users, new releases offer exciting features and new possibilities. For Admins, upgrades can often feel like a step into the unknown that brings about many questions:

How much downtime will the upgrade result in? After the upgrade, what problems, if any, should I expect? How stable can I trust my environment to be?

When I prepare for an upgrade, I want to leave as few of these questions unanswered as possible through a meticulously planned process. Today, I share with you my steps through that process.

Though this post is for upgrade beginners, it does assume moderate knowledge of Tableau Server functionality.

Assess Dependencies and Pick a Version

This step is often rushed, but is more important than many think. We must carefully consider the business’s needs for certain features, but always prioritize stability and security first. New features are great, but a consistent and available system is better.

To succeed in this step, you need to understand new features as they relate to business and security needs. Reference the Release Notes and check the Known Issues to see how they may concern your environment. While choosing your version, consider version maturity by looking at the number of maintenance releases. Newer versions have been implemented by fewer companies, which means less opportunity to find bugs. The more bugs that have already been discovered, the less bugs you and your users need to find!

Keep in mind your existing automation and custom applications to understand how they may change in an upgrade. With each new version, there may also be changes to management tools such as tabadmin/TSM, tabcmd, Postgres, or Tableau REST API.

Build your Upgrade Plan and Timeline

Create a Test Plan

For a successful test period, we must provide accountable testers with specific and structured test cases. Test case documents are the deliverable used to hold testers accountable for actually performing necessary testing. I do not want an email that says “Looks good to me” – I want an artifact proving that. After initial creation, test case documents can generally be reused and expanded upon for future upgrades.

Build test cases applicable to all functionality. Cover the following at minimum:

  • Workbook functionality (filtering and other interactions)
  • Granting and removing permissions
  • Subscriptions, scheduled and manual extract refreshes, and AD sync
  • Publishing data sources and workbooks
  • Downloading data sources and workbooks
  • Web editing

Create additional test plans for any custom Tableau applications or scripting processes.

Once you have your test cases built, recruit testers who will be accountable for testing their own reports in addition to overall server functionality. Enlist site admins and super users to identify critical testers and workbooks. 

Create a Communication Plan

Communicating with an audience is critical to change enablement, so we need to plan our communications to both testers and the wider audience. When it comes to downtime and change, too much communication is better than too little.

Schedule the following communications at minimum:

  • Call for upgrade testers
  • Instructions and testing information for testers
  • Alert to the broad audience of selected version and upgrade schedule
  • Reminders to testers to send their completed test cases back
  • Week out upgrade and planned outage reminder
  • Day-of upgrade and planned outage reminder
  • Post-upgrade notice of outage end

Create a Rollback and Contingency Plan

Ideally the upgrade is seamless – however, that is not always the case. We need to understand and plan for backing out in case things go south. Before upgrading, outline steps that must be taken to move the server back to its previous version, and when the next attempt will be made to upgrade. Plan to test this rollback in Non-Prod.

Upgrade Non-Prod

Upgrade Non-Prod to the selected version to create a test environment for the testers and admins. Admins and testers will identify and solve issues here before moving to Production. To maximize test validity, I recommend to first restore a backup from Production to duplicate the environment, thought this may not be possible for all environments. At a minimum, all identified critical reports identified in test planning should be published to Non-Prod pre-upgrade.

Depending on your version of Tableau, follow Tableau’s instructions for executing an upgrade. You should always take a final backup after the server is stopped, and I recommend a fresh restart of the servers between the uninstall and install if applicable. Remember to also upgrade TabCMD if it is used in your environment.

For initial validation, the admin team should go through test cases before sharing to the team.

Testing and Issue Remediation

All testers should execute test cases and return their results at a justified deadline. As issues emerge, they should be documented along with steps to remediate and issue criticality. Plan for at least a week, preferably two weeks, for issue remediation between test case deadline and planned upgrade. It is better to plan for more time than need to communicate upgrade delays.

Additional testing to be done by admins:

  • Run all custom applications and scripts in non-prod.
  • Simulate actual extract load by enabling schedules.

The above testing should be done off-hours to prevent additional load from affecting performance in the Production. The increased load can add stress to the data source systems, and cause Production refreshes to lag. 

Iterate on the Prod upgrade plan based on feedback and findings in Non-Prod.

Upgrade Production

After all of our hard work planning and testing, we’re ready for Production. This is typically done over a weekend to minimize user impact.

Once services are down, remember to run a final backup and topology export. This should then be moved to a non-Tableau directory for safe keeping. Depending on your version of Tableau, follow Tableau’s instructions for executing an upgrade. You should also upgrade TabCMD if it is used in your environment.

System Validation

We made it. Now let’s ensure everything is working properly. Validate that all services and processes are up and running. Run through your test cases yet again to ensure all functionality is working as expected.

Once that is done, check that custom applications and portals are working post-upgrade. If these initial validations come up clear, you are good to send your final communication to users alerting them that Tableau Server is back up and running.


That’s it! You now know how to plan a successful upgrade for Tableau Server. This may seem like a large emphasis on planning and testing, but that is exactly the kind of upgrade ritual that keeps things as low risk as possible. I like to think that as Admins, we do all of the worrying so users don’t have to. 

Feel free to use this as a checklist for planning your next upgrade. If you have any additional questions on upgrades, please reach out to our team of experts! 

Data Coach is our premium analytics training program with one-on-one coaching from renowned experts.

Accelerate and automate your data projects with the phData Toolkit