Customize and Tune a Connection

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

If you’re customizing a JDBC-based connection, you can also make customizations in a PROPERTY file. For details, see Use a PROPERTIES file to customize a JDBC connection.

About Special Characters

Special characters must be correctly escaped, and whether this is necessary can vary based on the character's position. For instance, if an equals sign '=' is included in the value, to the right of the initial '=', it must be properly escaped.

Example:

ServiceLocation=Region=east;Name=prod;

Should be written as: ServiceLocation=Region\=east;Name\=prod;

Use a TDC file to customize a connection

TDC (Tableau Datasource Customization) files are XML files with a “.tdc” filename extension. These files are used to customize 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>(also includes the class)section. For a built-in connector, the vendor name and driver name must match the connector’s class name. Usually, the vendor name matches the driver name. Two generic class names are used for the Other Databases connectors:

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

If an existing workbook or data source file has an enabled customization section already, Tableau uses only the customizations 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 doesn’t 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’s 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 customization variables
  • Vendor and driver names
  • The customizations themselves

The connection-customization section includes the following:

  • Class The data source you want to connect to and customize.
  • Enabled Specifies whether the TDC file connection customizations 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 customizations.

For more information, see Tableau JDBC Capability Customizations.

Use a PROPERTIES file to customize 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 includes 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 directory:

    My Tableau Repository/Datasources

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

    Windows: ProgramData\Tableau\Tableau Server\data\tabsvc\vizqlserver\Datasources

    Linux: /var/opt/tableau/tableau_server/data/tabsvc/vizqlserver/Datasources/

  • For Prep flows, place PROPERTIES files in these directories:

    Linux:

    /var/opt/tableau/tableau_server/data/tabsvc/flowprocessor/Datasources/

    /var/opt/tableau/tableau_server/data/tabsvc/flowminerva/Datasources/

    Windows:

    ProgramData\Tableau\Tableau Server\data\tabsvc\flowprocessor\Datasources

    ProgramData\Tableau\Tableau Server\data\tabsvc\flowminerva\Datasources

  • For virtual connections, place PROPERTIES files in this directory:

    Linux: /var/opt/tableau/tableau_server/data/tabsvc/minerva/Datasources/

    Windows: ProgramData\Tableau\Tableau Server\data\tabsvc\minerva\Datasources

After you save the file to the correct location, the properties are 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

Customize 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 customization.

Thanks for your feedback!Your feedback has been successfully submitted. Thank you!