Customize and Tune a Connection
You can make customizations to a connection string's parameters and to the connection's capabilities using a TDC file. This applies to both ODBC and JDBC connections.
If you’re customizing a JDBC-based connection, you can also modify the connection string parameters in a properties file. For details, see Use a properties file to customize a JDBC connection.
Important: TDC files can be utilized to customize the functionality of a connection or to diagnose and resolve issues related to connecting to your data. Tableau is unable to thoroughly test every potential modification you might make with these files. Creating and using TDC files requires manual editing and it is crucial to test them thoroughly before deploying them in a production environment.
Use a TDC file to customize a connection
Note: You can only have one TDC file per connector. If there are multiple TDC files referring to the same connector, only one will be applied.
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.
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'/>
<customization name='CAP_SOMETHING_ELSE' 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.
Here are two example TDC files: First, a generic ODBC connection, and second, a modification to a native Salesforce connection. Note these are for example purposes only and the customizations listed are not selected to accomplish a specific goal.
<?xml version='1.0' encoding='utf-8' ?>
<connection-customization class='genericodbc' enabled='true' version='8.10'>
<vendor name='Gen_ODBC_Vendor'/>
<driver name='Gen_Driver'/>
<customizations>
<customization name='CAP_FAST_METADATA' value='yes' />
<customization name='CAP_ODBC_BIND_FORCE_MAX_STRING_BUFFERS' value='yes' />
<customization name='CAP_ODBC_BIND_PRESERVE_BOM' value='yes' />
</customizations>
</connection-customization>
<?xml version='1.0' encoding='utf-8' ?>
<connection-customization class='salesforce' enabled='true' version='8.10'>
<vendor name='salesforce'/>
<driver name='salesforce'/>
<customizations>
<customization name='CAP_ODBC_EXPORT_CONTINUE_ON_ERROR' value='yes' />
<customization name='CAP_ODBC_EXPORT_FORCE_SINGLE_ROW_BINDING' value='yes' />
<customization name='CAP_ODBC_EXPORT_SUPPRESS_STRING_WIDTH_VALIDATION' value='no' />
</customizations>
</connection-customization>
For more information about the customizations available, see:
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”.
Installing tdc and properties files
Once a customization file (either TDC or properties) is created, it must be placed in specific "Datasources" directories for it to be discovered and used by Tableau products. For example, if users will be publishing content from Tableau Desktop to Tableau Server, the customizations should be copied to both product directories.
After the file is copied to the appropriate directories, Tableau (including all nodes if using Tableau Server) must be restarted for the changes to be recognized. See below for the directory path in a default installation.
Tableau desktop application paths
- Desktop/Windows:
C:\Users\myuser\My Tableau Repository\Datasources - Desktop/Mac:
~/Documents/My Tableau Repository/Datasources - Prep Builder/Windows:
C:\Users\myuser\Documents\My Tableau Prep Repository\Datasource - Prep Builder/Mac:
~/Documents/My Tableau Prep Repository/Datasources - Bridge/Windows:
C:\Users\myuser\Documents\My Tableau Bridge Repository\Datasources - Bridge/Linux:
/root/Documents/My_Tableau_Bridge_Repository/Datasources/
Tableau Server paths
Note: Customization files must be copied to the appropriate directory for every server node in use.
- Windows:
- Server:
C:\Program Files\Tableau\Tableau Server\data\tabsvc\vizqlserver\Datasources
C:\Program Files\Tableau\Tableau Server\packages\bin.<build number> - Virtual Connections:
C:\Program Files\Tableau\Tableau Server\data\tabsvc\minerva\Datasources - Prep Flows:
C:\Program Files\Tableau\Tableau Server\data\tabsvc\flowprocessor\Datasources - Prep Web Authoring:
C:\Program Files\Tableau\Tableau Server\data\tabsvc\flowminerva\Datasources - Linux:
- Server:
/var/opt/tableau/tableau_server/data/tabsvc/vizqlserver/Datasources/ - Virtual Connections:
/var/opt/tableau/tableau_server/data/tabsvc/minerva/Datasources/ - Prep Flows:
/var/opt/tableau/tableau_server/data/tabsvc/flowprocessor/Datasources/ - Prep Web Authoring:
/var/opt/tableau/tableau_server/data/tabsvc/flowminerva/Datasources/
After you save the custom TDC or properties files to the correct location, and restart the applications, they will be applied to all connections for that same data source type.