Upgrade Tableau Server with External Repository for a New Major Version of PostgreSQL

When there is a change in the PostgreSQL major version requirement for Tableau Server, there are some specific instructions you must follow to ensure that your Tableau Server upgrade is successful. For example, Tableau Server 2020.4 requires the repository to use PostgreSQL version 12. This is a major version change from PostgreSQL version 9.x used in Tableau Server versions earlier than 2020.4. So if you are upgrading from an earlier version of Tableau Server to version 2020.4 or later, you will need to take the steps described in the following sections to complete the upgrade.

This topic also includes the product compatibility between PostgreSQL and Tableau Server.

Before you upgrade

You cannot do an in-place upgrade to update the PostgreSQL version on your existing PostgreSQL DB instance on Amazon RDS or Azure Database for PostgreSQL DB. Instead, you must create a new instance and point the Tableau Server to the new instance during upgrade. Use the following information to create a new instance and prepare for the upgrade:

  1. Create a new instance of PostgreSQL Database instance:
    1. Create a PostgreSQL DB Instance on AWS Relational Database Service (RDS)
    2. Create a Azure Database PostgreSQL Instance on Azure
    3. Create a PostgreSQL Database as a Stand-alone Installation
  2. SSL connections are not required but recommended. If you want to set up SSL connections for communications between Tableau Server and the External Repository, do the following:
    1. Amazon RDS: See Using SSL to Encrypt the Connection to a DB Instance(Link opens in a new window).

    2. Azure Database: See Configure TLS connectivity for Azure Database for PostgreSQL(Link opens in a new window).
    3. Stand-Alone PosgreSQL Instance: See Configure SSL.
  3. Create a configuration file for the new instance you created in step 1.

    1. Create a json file with the following configuration settings:

       "masterUsername":"<admin user name>",
       "host":"<instance host name>",
       "port":"<port number>"
      • flavour: This is the type of external service you are going to use for Tableau Server repository.

        • Amazon RDS: use ‘rds’.
        • Azure DB: use "azure"
        • Stand-alone PosgreSQL instance: "generic"
      • masterUsername:

        • Amazon RDS: Use ‘rails’ for the username. This is the user that you specified when creating the RDS instance.

          You must use ‘rails’ as the masterUsername. This is required for the external repository to work with Tableau Server properly.

        • Azure Database or Stand-Alone PosgreSQL Instance: Choose a username that meets your requirements. We recommend using postgres as the Administrator username. If you choose to use a different username, make sure that the username does not start with pg or azure. The username also cannot be rails, tblwgadmin, tableau, readonly or tbladminviews.
      • masterPassword: This is the same password you specified when creating the PostgreSQL database instance.

      • host: This is the endpoint of your PostgreSQL database instance.

      • port: The database port you specified when creating the PostgreSQL DB instance. Default port for PostgreSQL is 5432.

Tableau Server Upgrade

Note: If you are using Tableau Server External Repository, you must upgrade Tableau server using the command line option.

The following are the high level steps of how to specify the external repository parameters when running the upgrade script.

For a full walk-through of the Tableau Server upgrade process, see Upgrading from earlier versions.

  1. On the Tableau Server, open a command prompt as administrator.

    Note: You must open a new command window because the Setup program updates the path for the new installation.

  2. Navigate to the scripts folder for your new installation.

    By default:

    C:\Program Files\Tableau\Tableau Server\packages\scripts.<version_code>\

  3. Run the upgrade script and specify the configuration file and the SSL certificate:

    upgrade-tsm.cmd --external-repository-config-file=<json config file> --external-repository-cert-file=<SSL certificate file>

Product Compatibility

The table below lists the version of PostgreSQL that is supported with Tableau Server. Use this table to determine the version of PostgreSQL to install for your External Repository.

Amazon RDS support: External Repository using Amazon RDS is supported with Tableau Server version 2019.3 and later.
Azure Database support: External Repository using Azure Database instance is supported with Tableau Server version 2020.4 and later.
Stand-alone PostgreSQL instance support: External Repository using a stand-alone installation of PostgreSQL database is supported with Tableau Server version 2021.2 and later.

The table below includes two columns:

  1. PostgreSQL version shipped with Tableau Server, which is the version that is installed with Tableau Server for local Repositories.
  2. All PosgreSQL versions supported for External Repository.

- For PostgreSQL versions earlier than version 10, the first two digits indicate the major version, and the minor version is represented by the last digit. For example, in the version 9.4.1, 9.4 indicates the major version and the .1 indicates the minor version.
- For PostgreSQL versions 10 or later, the first digit indicates the major version, and the minor version is the represented by the last digit. For example, in the version 11.1, 11 is the major version and .1 is the minor version.
- A PostgreSQL version with a major version equal to, and a minor version greater than, the Postgres version shipped with Tableau server is always acceptable for use with the external repository, along with any explicitly allowed older versions.

Tableau Server Version PostgreSQL Version (Shipped with Tableau Server) Alternate PosgreSQL Versions supported for External Repository
2019.3 - 2019.3.3 9.6.11

9.6.x, where x is greater than 11

2019.3.4 - 2019.3.10 9.6.15 9.6.x, where x is greater than 15
2019.3.11 - 2019.3.14 9.6.17 9.6.15, or 9.6.x, where x greater than 17
2019.4 - 2019.4.1 9.6.14 9.6.x, where x is greater than 14
2019.4.2 - 2019.4.6 9.6.15 9.6.x, where x is greater than 15
2019.4.7 - 2019.4.13 9.6.17 9.6.15, or 9.6.x, where x is greater than 17
2020.1 - 2020.1.6 9.6.15 9.6.x, where x is greater than 15
2020.1.7 - 2020.3.2 9.6.17 9.6.15, or 9.6.x, where x is greater than 17
2020.4 12.2

12.1, or 12.x, where x is greater than 2

2020.4.1 12.4 12.4 or 12.x, where x is greater than 4

2020.4.2 – 2020.4.7

2021.1 – 2021.4

2021.2 - 2021.2.1.4

12.5 12.5 or 12.x where x is greater than 5

2020.4.8 and later versions of 2020.4

2021.1.5 and later versions of 2021.1

2021.2.2 and later versions of 2021.2.2

2021.3 and later

12.6 12.6 or 12.x where x is greater than 6

Who can do this

Tableau Server Administrators can upgrade and configure Tableau Server.

Thanks for your feedback!