There are times when you might want to modify the connection made with a native connector. You can do this by creating a TDC (Tableau Datasource Customization) file that passes configuration changes to the connection using the odbc-connect-string-extras customization. This article applies to connectors that use an ODBC driver.
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.
Modify the connection string
When Tableau connects using an ODBC driver, it creates and passes a connection string to the driver manager. The connection string identifies the driver and contains all the parameters for the driver.
Here's an example connection string:
Let's say you want to override the DRIVER value of BagelDB Driver with BagelDB Driver 2.0 and add a port number so that the connection string passed to the driver manager is modified to:
DRIVER=BagelDB Driver 2.0;SERVER=bageldb.lan;UID=creamcheese;PWD=bagel;PORT=54321
You can modify the connection string parameters in by using a TDC and odbc-connect-string-extras. In general, the only parameter than can be overridden is DRIVER. Other parameters are appended to the end of the connection string. See how to "Use a TDC file" below.
Note: Because of security restrictions, there is limited support for the odbc-connect-string-extras customization on Tableau Online. Some parameters might not be supported.
Use a safelist to reduce security risk
Important: The following procedure needs to be done by a Tableau Server administrator on Tableau Server and should be evaluated by your IT department for compliance with your organization’s security guidelines.
The odbc-connect-string-extras customization can present a security risk. Your Tableau Server administrator can manage this risk by specifying a list of approved parameters in a safelist:
- Any parameters specified by odbc-connect-string-extras that are not on the list are filtered out.
- If there are no parameters specified in the list, then all parameters are allowed.
The security list is a comma-separated list with no spaces in between.
For example, to add the parameters UseDeclareFetch and App to the safelist, run the following commands:
tsm configuration set -k native_api.ODBCConnectStringSecurityList -v UseDeclareFetch,App --force-keys
tsm pending-changes apply
For information about running tsm commands, see tsm Command Line Reference in the Tableau Server Help.
Use a TDC file
A TDC file is an XML file that contains a vendor name, driver name, and <connection-customization> section. For a native connector, the vendor name and driver name must match the connector’s class name. See the "Native connector class list" below for values. Any existing workbook or data source file that already has an enabled customization section will use only the customizations that it supplies, not the TDC file.
When you create a TDC file, you must save it to the My Tableau Repository\Datasources folder so that it can be used by your connection. If you create a workbook that you want to publish to Tableau Server, then you need to save the TDC file to the server as well. For more information, see Using a .tdc File with Tableau Server in Tableau Knowledge Base.
Note: If you create a data source or workbook with customized odbc-extras, the odbc-extras is saved in the workbook. Because of this, you can publish a workbook or data source to Tableau Server without having to install the TDC file on Tableau Server.
In the TDC file, you can use the odbc-connect-string-extras customization to append attributes or override the DRIVER attribute to the connection string.
Create a TDC file
- Open a plain text editor, such as Notepad or Notepad++.
- Copy the information from the sample provided below, paste it into your text file, and then specify the class, vendor name, and driver name value. For native Tableau connectors, use the same value for class, vendor name, and driver name.
- Save the file with a .tdc extension—for example, mybagel.tdc—to the My Tableau Repository\Datasources folder.
- Enter the customizations you want to make to the connection.
<connection-customization class='bagelDB' enabled='true' version='19.1'>
<vendor name='bagelDB' />
<driver name='bagelDB' />
<customization name='odbc-connect-string-extras' value='DRIVER=BagelDB Driver 2.0;PORT=54321' />
Native connector class list
Find your connector in the table below to learn the class value to use in a TDC file.
Amazon EMR (Hive)
Azure SQL Data Warehouse
Google Cloud SQL
Hortonworks Hadoop Hive
IBM PDA (Netezza)
MapR Hadoop Hive
Microsoft SQL Server
MongoDB BI Connector
Other Databases (ODBC)
Pivotal Greenplum Database
SAP Sybase ASE
SAP Sybase IQ
Tibco Data Virtualization