Pre-Upgrade Checklist

Product(s): Tableau Server
Version(s): 9.0, 8.3, 8.2, 8.1, 8.0, 9.1
Last Modified Date: 16 Aug 2016

This article is for customers who are preparing to upgrade Tableau Server. It describes several best practices that will help your upgrade go smoothly. If you are upgrading from a version earlier than version 7.0, please contact Tableau Customer Support for assistance.

For additional upgrade resources, see Upgrade to Tableau Server.

Credentials, setup files, and customizations

Before you upgrade, make sure you have the following:

  • User account credentials: For each machine you’re upgrading, you need credentials for a user account with local admin permissions.

  • Run As account credentials: Confirm that you have the user name and password for Tableau Server’s Run As account. This is the account you configured Tableau Server to run under when you installed the earlier version of Tableau Server. You can view the Run As username by clicking Start then navigating to All Programs > Tableau Server > Configure Tableau Server.

  • Setup files: In addition to having the .exe for the upgrade you’re about to perform, you should locate or re-download the Setup .exe for the server version you currently have in production (see the Downloading Tableau Products article). If something unexpected happens during the upgrade, this can help you recover more quickly.

While Tableau retains configuration settings during an upgrade, it’s a best practice to also note any customizations you have made so that you can verify them later. These include configuring SSL, changing Tableau’s default port and time out values, as well as using custom logos. See the Upgrade topic in the Server Online Help for details on where these items are configured. If you customized your pgsql.use.vacuum_job setting in Tableau Server version 8.1 or earlier, see Enable "pgsql.use_vacuum_job" if previously disabled, below.

It's also a best practice to understand the compatibility of workbooks between Tableau Server and Tableau Desktop before upgrading. See the Desktop and Server Compatibility article for more information.

tabcmd Version

A new version of tabcmd is released with every release of Tableau Server. If you installed the command line utility on computers that are not running Tableau Server, you may need to upgrade tabcmd on those computers when you upgrade Tableau Server. See the Installing Tabcmd article for more information.

Bit Version

Starting with version 8.1, Tableau Server is provided as a native 64-bit application as well as a 32-bit application. Earlier versions of Tableau Server were only available as 32-bit. If you were previously running the 32-bit version of Tableau Server on a 64-bit operating system, upgrading to the 64-bit version of Tableau Server is recommended. See the Technical Specifications for Tableau Server for the minimum requirements to run the 64-bit version of Tableau Server.

If you are upgrading a distributed installation of Tableau Server to version 9.0, note that the entire cluster must run the same bit version—either all 32-bit or all 64-bit Tableau server software.

Check your product maintenance status

If you attempt to upgrade Tableau Server from a server whose maintenance has expired, the result will be an unlicensed instance of Tableau Server.

To check your server’s maintenance expiration date:

  • Select Start > All Programs > Tableau Server > Manage Product Keys and look under the Maintenance Expires column.

If your maintenance has expired, select the key and click Refresh. If the maintenance doesn't update, refer to the Viewing and Paying Tableau Invoices article. Reactivating the product key will be part of Tableau Server Setup. If your maintenance is still current, proceed to the next section.

Enable "pgsql.use_vacuum_job" if previously disabled

Starting with version 8.2, Tableau Server uses version 9.3.x of PostgreSQL as its internal database. Earlier versions of PostgreSQL had issues with its autovacuum task on Windows, which Tableau addressed by adding the pgsql.use_vacuum_job set option. A small number of customers set this option to true to disable the autovacuum task normally performed by PostgreSQL. If you were one of those customers who previously disabled the autovacuum task, you must enable it before you upgrade to version 8.2 or higher by setting pgsql.use_vacuum_job to -d. Here's how:

  1. Open a command prompt as an administrator.
  2. Navigate to the Tableau Server "bin" directory. For example, type the following: cd "C:\Program Files\Tableau\Tableau Server\[version]\bin".

    Replace [version] with the version number of Tableau Server that you are currently running.

  3. Stop the server: tabadmin stop.

  4. Enable the autovacuum task by typing the following: tabadmin set pgsql.use_vacuum_job -d.

  5. Run the config command: tabadmin config.

  6. Start the server: tabadmin start.

Run cleanup

Running the tabadmin cleanup command removes unnecessary files from the Tableau Server system. You should run cleanup once with the server running, which allows it to act on extraneous files in the Tableau database, and once with the server stopped, which allows it to remove log files.

To run tabadmin cleanup:

  1. Open a command prompt as an administrator.
  2. Navigate to the Tableau Server "bin" directory. For example, type the following: cd "C:\Program Files (x86)\Tableau\Tableau Server\[version]\bin"

    Replace [version] with the version number of Tableau Server that you are currently running.

  3. Confirm that the server is running: tabadmin status.

  4. Run cleanup by typing the following: tabadmin cleanup.

  5. Stop the server: tabadmin stop.

  6. Run cleanup again: tabadmin cleanup.

Keep the server stopped to create a backup (next).

Create the backup file

In addition to your regular Tableau Server backups, it's a best practice to create a backup just prior to upgrading.

The tabadmin backup command creates a .tsbak file containing data from your repository, data extracts, and server configuration. After you create the file, store it on a separate computer. If you are creating a backup using Tableau Server version 8.0 or earlier, you must stop the server before creating a backup. Starting with version 8.1, you can create a backup without stopping the server first.

Since a Tableau backup file (.tsbak) includes configuration information, a backup of a distributed installation of Tableau Server will include configuration information about the worker nodes, including their IP addresses. If you don't want this information to be restored, use the --no-config option when you restore the backup file to your new installation. Note that with this option, no configuration information is restored, including any manual configuration changes you made on the primary Tableau Server.

Windows XP and Windows Server 2003: If you are running a distributed installation of Tableau Server and have a worker running Windows XP or Windows Server 2003 SP1 or higher, you must remove it from the configuration before upgrading. These operating systems are not supported platforms. If you have a worker running one of these operating systems and it was hosting extract data, the data it was hosting can be migrated to a new machine by following the steps in the "New Machine Upgrade – Migrate Existing Content” section of the Upgrading Tableau Server article

To create a backup file:

  • From your Tableau Server bin directory on the primary Tableau Server machine, type the following:

    tabadmin backup <filename> -d

    Replace <filename> with the name of your backup file. The –d is optional; if you include it, the current date is appended to the file name.

Make sure that you save the backup file in a location outside the Tableau Server folder (on the desktop for example). This prevents the backup file from being deleted during uninstall.

Note: If you need to rollback to the back-up version, follow the procedure outlined in the Rolling Back to an Earlier Installation of Tableau Server article.


Alternate Search Terms:upgrade, upgrading, install, installation, maintenance, tabadmin, backup, back-up, back up
Did this article resolve the issue?