Customize the Connection String for a Native Connector

Version 2

    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:

     

       DRIVER=BagelDB Driver;SERVER=bageldb.lan;UID=creamcheese;PWD=bagel;

     

    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.

     

    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

     

    1. Open a plain text editor, such as Notepad or Notepad++.
    2. 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.
    3. Save the file with a .tdc extension—for example, mybagel.tdc—to the My Tableau Repository\Datasources folder.
    4. 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' />

      <customizations>

        <customization name='odbc-connect-string-extras' value='DRIVER=BagelDB Driver 2.0;PORT=54321' />

      </customizations>

    </connection-customization>

     

    Native connector class list

     

    Find your connector in the table below to learn the class value to use in a TDC file.

     

    Connector

    Class

    Actian Matrix

    paraccel

    Actian Vector

    vectorwise

    Amazon Aurora

    aurora

    Amazon EMR (Hive)

    awshadoophive

    Amazon Redshift

    redshift

    Spark SQL

    spark

    Aster Database

    asterncluster

    Azure SQL Data Warehouse

    azure_sql_dw

    Cloudera Hadoop

    hadoophive

    Denodo

    denodo

    Exasol

    exasolution

    Firebird

    firebird

    Google Cloud SQL

    googlecloudsql

    Hortonworks Hadoop Hive

    hortonworkshadoophive

    IBM BigInsights

    bigsql

    IBM DB2

    db2

    IBM PDA (Netezza)

    netezza

    Kognitio

    kognitio

    MapR Hadoop Hive

    maprhadoophive

    MariaDB

    mariadb

    MarkLogic

    marklogic

    MemSQL

    memsql

    Microsoft SQL Server

    sqlserver

    MonetDB

    monetdb

    MongoDB BI Connector

    mongodb

    MySQL

    mysql

    Oracle Essbase

    essbase

    Other Databases (ODBC)

    genericodbc

    Pivotal Greenplum Database

    greenplum

    PostgreSQL

    postgres

    Presto

    presto

    Progress OpenEdge

    progressopenedge

    SAP HANA

    saphana

    SAP Sybase ASE

    sybasease

    SAP Sybase IQ

    sybaseiq

    Snowflake

    snowflake

    Splunk

    splunk

    Teradata

    teradata

    Tibco Data Virtualization

    composite

    Vertica

    vertica