Customise and Tune a Connection

You can make customisations to a connection using a TDC file.

If you are customising a JDBC-based connection, you can also make customisations in a PROPERTY file. For details, see Use a PROPERTIES file to customise a JDBC connection.

Use a TDC file to customise a connection

TDC (Tableau Datasource Customisation) files are XML files with a “.tdc” file name extension. These files are used to customise Tableau-specific settings. For ODBC-based connection, you can also use a TDC file to define parts of the ODBC and SQL standards that the ODBC driver supports.

A TDC file contains a vendor name, driver name and <connection-customization> section. For a built-in connector, the vendor name and driver name must match the connector’s class name. In most cases, the vendor name matches the driver name. Two generic vendor names are used for the Other Databases connectors:

  • For the Other Databases (JDBC) connector, the required vendor name is "genericjdbc".
  • For Other Databases (ODBC) connector, the required vendor name is "genericodbc".

If an existing workbook or data source file has an enabled customisation section already, Tableau uses only the customisations it defines and not any defined in the TDC file.

For more information, see Using a TDC File with Tableau Server(Link opens in a new window) in Tableau Knowledge Base.

Important: Tableau does not test or support TDC files. These files should be used as a tool to explore or occasionally address issues with your data connection. Creating and maintaining TDC files requires careful manual editing, and there is no support for sharing these files.

Structure of a TDC file

Each TDC file follows this basic structure:

<connection-customization class=DSCLASS enabled='true' version='10.0'>
    <vendor name=VENDOR />
    <driver name=DRIVER />
    <customizations>
        <customization name='CAP_FAST_METADATA' value='yes'/>
        ...
    </customizations>
</connection-customization>

A TDC file has three main sections:

  • Connection customisation variables
  • Vendor and driver names
  • The customisations themselves

The connection-customization section includes the following:

  • Class The data source you want to connect to and customise.
  • Enabled Specifies whether the TDC file connection customisations are applied. In the TDC file, always set to “true”.
  • Version Tableau ignores the version number.

The next section is crucial because it identifies the vendor name and driver name of the database provider for this TDC file's data source. Each TDC file can bind to only one data source type. For our native data sources, these names must both match the data source class name; for example, “teradata” for our Teradata connections. For ODBC data sources, the vendor name and driver name of the TDC file must match what is reported to Tableau by the database and driver; for example, “SQLite” and “SQLite3 ODBC Driver”, respectively.

The final section lists the actual connection customisations.

For more information, see Tableau JDBC Capability Customisations.

Use a PROPERTIES file to customise a JDBC connection

PROPERTIES files are used by JDBC and passed directly through to the JDBC driver. These are plain-text files with a “.properties” filename extension. They contain key-value pairs for each connection parameter.

Using a PROPERTIES file with a JDBC connection is similar to using the odbc-connect-string-extras parameter in a TDC file for ODBC connections.

Note: A PROPERTIES file should be in Latin-1 format (see https://en.wikipedia.org/wiki/.properties(Link opens in a new window)). However, as long as it contains only ASCII characters, you can safely save the file in UTF-8 format without a BOM (byte order mark).

In the file, place each key-value pair on its own line with no delimiter. Give the file the same name as its corresponding connector, but with a “.properties” filename extension. For example, the PROPERTIES file for the SAP HANA connector would be “saphana.properties”.

For Tableau Desktop, place PROPERTIES files in this folder:

My Tableau Repository/Datasources

To enable a PROPERTIES file for Tableau Server, place it in this folder for each Server node:

  • Windows: ProgramData\Tableau\Tableau Server\data\tabsvc\vizqlserver\Datasources
  • Linux: /var/opt/tableau/tableau_server/data/tabsvc/vizqlserver/Datasources/

Once you save the file to the correct location, the properties will be applied to all JDBC connections for that same data source type.

Publish a workbook using a JDBC-based connection

To publish a workbook from a JDBC-based connection, you must include a copy of the PROPERTIES file on both Tableau Desktop and Tableau Server computers.

See also

Customise the Connection String for a Native Connector(Link opens in a new window) – This article in Tableau Community describes how to modify the connection made with a native connector using the odbc-connect-string-extras customisation.

Thanks for your feedback!