Getting started with Devart ODBC Driver for Salesforce

Quick start: Connect to Salesforce with ODBC

To connect to Salesforce using the Devart ODBC Driver:

1. Download and install the Driver for Windows, macOS, or Linux.
2. Activate the Driver using your activation key, or continue with the 30-day trial. On Windows and macOS, take this step in the installer; on Linux, run the activator afterwards.
3. Create an ODBC data source (DSN) and select Devart ODBC Driver for Salesforce.
4. Configure the connection by selecting the Salesforce environment and an authentication method: OAuth 2.0, user ID and password with a security token, or server-to-server credentials.
5. Use the DSN in your ODBC-compatible application to connect to Salesforce and work with its data.

The following sections provide detailed installation and configuration instructions for each of the supported operating systems.

Prerequisites

Before you begin, make sure your environment meets the following requirements:

• Operating system: 32-bit or 64-bit Windows, including Windows Terminal Server; macOS (x64 or ARM64, including Apple silicon); Linux (32-bit or 64-bit).
• ODBC driver manager: Included with Windows. On macOS, install iODBC. On Linux, install unixODBC.
• Connection details: A Salesforce account with API access and the credentials for the authentication method you plan to use: a Salesforce login for OAuth 2.0, a user ID, password, and security token for password-based authentication, or the consumer key and consumer secret of a Salesforce app for server-to-server authentication.
• DSN configuration tool (optional): On macOS and Linux, you can use Devart ODBC Administrator to create and manage data sources through a graphical interface. The tool is distributed separately from the Driver and is available on the Devart website. Alternatively, configure data sources manually in the odbc.ini file.
• Activation key: A purchased version of the Driver requires an activation key. For evaluation purposes, you can use the trial version, which is valid for 30 days from the date of installation.
• Administrator rights: Required to install the Driver on all supported operating systems.

For a complete list of supported Salesforce data types, operating systems, and third-party tools, see the ODBC Driver for Salesforce compatibility page.

Install the ODBC Driver

Installing Devart ODBC Driver for Salesforce is straightforward. All you need to do is download the package for your operating system and follow the installation instructions.

Install the Driver on Windows

1. Download the ODBC Driver for Salesforce from the Devart website, open it, and click Next.

2. Read the License Agreement, select I accept the agreement, and click Next.

3. On the Select Destination Location page, keep the default folder or click Browse to choose another one, and click Next.

4. On the Select Components page, select the components to install, then click Next.

5. On the Select Start Menu Folder page, specify the folder for the Driver shortcuts. To skip creating a Start Menu folder, select Don't create a Start Menu folder. Click Next, then click Install.

6. On the License Information page, select Input activation key and enter your key. You can find it in the registration email or your Customer Portal. To open the Customer Portal, click Get Activation Key.

If the activation key is saved on your computer, click Load Activation Key and select the corresponding file.

To evaluate the Driver without a purchased key, select Trial evaluation.

7. Click Next, then click Finish to complete the installation.

Install the Driver on macOS

1. Download the ODBC Driver for Salesforce PKG file from the Devart website and double-click the package to run it.

2. Run the installer and click Continue.

3. Read the license agreement, then click Agree.

4. On the Registration page, select Input activation key and enter your key, or click Load Activation Key and select the file that contains it. To evaluate the Driver without a purchased key, select Trial evaluation. Click Continue.

5. On the Installation Type page, click Install. To choose which components to install, click Customize first. When the installation finishes, click Close.

You can activate the Driver later from the Terminal: navigate to /Library/ODBC/Devart/Salesforce and run the activator with your key.

cd /Library/ODBC/Devart/Salesforce
sudo ./salesforceodbcactivator -a <your_activation_key>

Install the Driver on Linux

On Linux, the Driver requires the unixODBC driver manager, which must be installed separately. Follow the track that matches the package format of your distribution.

DEB-based distributions, such as Ubuntu and Debian

The commands below apply to Ubuntu 26.04 LTS, 24.04 LTS, and 22.04 LTS.

1. Install the unixODBC driver manager.

sudo apt-get update
sudo apt-get install -y unixodbc odbcinst

2. Download the DEB package for your architecture from the Devart website.

3. Open a terminal, navigate to the folder that contains the package, and install the package and its required dependencies.

cd ~/Downloads
sudo apt-get install -y ./devartodbcsalesforce_amd64.deb

4. Activate the Driver. Navigate to the folder where it is installed and run the activator with your key.

cd /usr/share/devart/odbcsalesforce
sudo ./salesforceodbcactivator -a <your_activation_key>

5. Verify that the Driver is registered.

odbcinst -q -d

The output should include [Devart ODBC Driver for Salesforce].

Then verify that the DSN created during installation is registered.

odbcinst -q -s

The output should include the automatically created DEVART_SALESFORCE DSN.

RPM-based distributions, such as CentOS, RHEL, and Fedora

The commands below apply to CentOS Stream 9 and 10.

1. Install the unixODBC driver manager.

sudo dnf install unixODBC

2. Download the RPM package.

sudo dnf install -y epel-release
sudo dnf install -y gtk2

3. Open a terminal, navigate to the folder that contains the package, and install the package and its required dependencies.

cd ~/Downloads
sudo dnf install ./devart-odbc-salesforce.x86_64.rpm

4. Activate the Driver. Navigate to the installation folder and run the activator with your key.

cd /usr/local/devart/odbcsalesforce
sudo ./salesforceodbcactivator -a <your_activation_key>

5. Verify that the Driver is registered.

odbcinst -q -d

The output should include [Devart ODBC Driver for Salesforce].

Then verify that the DSN created during installation is registered.

odbcinst -q -s

The output should include the automatically created DEVART_SALESFORCE DSN.

Configure an ODBC data source

In this guide, you create a Data Source Name (DSN) for the ODBC connection and verify the connection details. A DSN stores connection settings, such as the Salesforce server URL, the authentication method, and credentials that applications use to connect to Salesforce. Applications can also connect without a DSN by passing the same parameters in a connection string.

Configure a DSN on Windows

1. In Windows Search, enter ODBC Data Sources and open the ODBC Data Source Administrator that matches the bitness of your application.

2. Go to the User DSN, System DSN, or File DSN tab, and click Add:

• User DSN — Available only to the user who creates it.
• System DSN — Available to all users on the computer.
• File DSN — Stores connection settings in a file that can be shared between computers where the required ODBC driver is installed.

3. In the Create New Data Source dialog, select Devart ODBC Driver for Salesforce, and click Finish.

4. In the Devart ODBC Driver for Salesforce Configuration dialog, enter a Data Source Name and an optional Description, then specify the Salesforce server (the Salesforce login URL):

• login.salesforce.com is the default server.
• test.salesforce.com is used for a sandbox.
• Your domain, such as https://yourcompany.my.salesforce.com, is used for connecting to a custom domain.

5. In the Authentication field, select the authentication method and provide the corresponding credentials.

OAuth 2.0 (recommended)

Select OAuth 2.0 and click Sign in to Salesforce. In the browser window that opens, sign in to your Salesforce account and allow the requested permissions. The Refresh Token field will be filled automatically.

To authenticate through your own Salesforce connected app or external client app, also enter its Consumer Key and Consumer Secret. For more information, see Configure OAuth authentication.

User ID and password

Select User ID and Password, then enter the following:

• User ID — Your Salesforce username.
• Password — Your Salesforce password.
• Security Token — The security token of your Salesforce account. To get a new token, in Salesforce, go to your personal settings and click Reset Security Token to have the token sent to your email. For more information, see Get a security token.

Server-to-Server authentication

Select the Server-to-Server authentication method and enter the Consumer Key and Consumer Secret of a Salesforce external client app. For more information, see Get credentials for server-to-server authentication.

6. Optional: If you connect through a proxy server, specify the Proxy Server, Port, Proxy User ID, and Proxy Password.

7. Optional: Click Test Connection to verify the connection settings.

8. When the configuration is completed, click OK to save the DSN settings.

To configure connection and query timeouts, metadata caching, retrieval of deleted records, and compatibility behavior, use the Advanced Settings tab of the same dialog.

Configure a DSN on macOS

DSNs are managed in Devart ODBC Administrator, a graphical tool that is distributed separately from the Driver. Download and install it before you continue.

1. Open Devart ODBC Administrator (root), select System DSN (recommended), and click Add. Enter your password when prompted.

2. In the Choose a driver dialog, select Devart ODBC Driver for Salesforce and click OK.

3. In the Devart ODBC Driver for Salesforce Configuration dialog, enter the Data Source Name, an optional Description, and the Server address. Then select the authentication method and provide the corresponding credentials.

OAuth 2.0

In the Authentication field, select OAuth 2.0, click Sign in to Salesforce, and complete the sign-in in your browser. The Refresh Token field will be filled in automatically. If you want to use your own Salesforce app, also enter its Consumer Key and Consumer Secret.

User ID and password

In the Authentication field, select User ID and Password, then enter your Salesforce User ID, Password, and Security Token.

Server-to-Server authentication

In the Authentication field, select the server-to-server authentication method, then enter the Consumer Key and Consumer Secret of your Salesforce external client app.

4. Optional: Click Test Connection to verify the connection details. Then click OK to save the DSN settings.

Alternatively, edit the odbc.ini file directly. The installation creates a sample DSN named DEVART_SALESFORCE that uses password-based authentication and that you can adjust. Use /Library/ODBC/odbc.ini for a system-wide DSN or ~/.odbc.ini for a user-specific one.

[DEVART_SALESFORCE]
Driver=Devart ODBC Driver for Salesforce
Data Source=https://login.salesforce.com
UserID=your_salesforce_user_id
Password=your_salesforce_password
SecurityToken=your_security_token

Save and close the file.

Configure a DSN on Linux

As on macOS, Devart ODBC Administrator is distributed separately from the Driver. Download and install it from the Devart website before you continue.

For DEB-based distributions:

cd ~/Downloads
sudo apt-get install -y ./devartodbcadministrator_amd64.deb

For RPM-based distributions:

cd ~/Downloads
sudo dnf install ./devart-odbc-administrator.x86_64.rpm

After installing the ODBC Administrator, proceed to configure a DSN.

1. Open Devart ODBC Administrator (root), select the System DSN tab, and click Add.

2. In the Choose a driver dialog, select Devart ODBC Driver for Salesforce and click OK.

3. In the Devart ODBC Driver for Salesforce Configuration dialog, enter the Data Source Name, an optional Description, and the Salesforce Server address. Select the authentication method and provide the corresponding credentials, as described for macOS.

4. Optional: Click Test Connection to verify the connection settings. If the test succeeds, click OK to save the DSN settings.

Alternatively, define the DSN in /etc/odbc.ini. The installation creates a sample DSN named DEVART_SALESFORCE that uses password-based authentication and that you can adjust. Use /etc/odbc.ini for a system-wide DSN or ~/.odbc.ini for a user-specific one.

[DEVART_SALESFORCE]
Driver=Devart ODBC Driver for Salesforce
Data Source=https://login.salesforce.com
UserID=your_salesforce_user_id
Password=your_salesforce_password
SecurityToken=your_security_token

To verify the data source from a terminal, connect to it with isql, the command-line tool provided by unixODBC. Replace <your_dsn_name> with the name of your DSN.

isql -v <your_dsn_name>

Connect to Salesforce using a connection string

In addition to using a DSN, you can connect to Salesforce by specifying the connection parameters directly in an ODBC connection string. This type of connection is known as a DSN-less connection.

The following table summarizes when to use each connection method.

Use the connection string that matches your authentication method.

OAuth 2.0

DRIVER={Devart ODBC Driver for Salesforce};Server=login.salesforce.com;Authentication=OAuth;Refresh Token=myRefreshToken

If you use your own Salesforce app, add Consumer Key=myConsumerKey;Consumer Secret=myConsumerSecret to the string.

User ID and Password

DRIVER={Devart ODBC Driver for Salesforce};Server=login.salesforce.com;User ID=myUsername;Password=myPassword;Security Token=mySecurityToken

Server-to-Server

DRIVER={Devart ODBC Driver for Salesforce};Server=login.salesforce.com;Authentication=ServerToServer;Consumer Key=myConsumerKey;Consumer Secret=myConsumerSecret

Replace the placeholders with your actual Salesforce credentials.

You can also specify advanced connection parameters to configure timeouts, metadata caching, ODBC behavior, and other Driver settings. For the complete list of supported options, see Salesforce ODBC connection string parameters.

Troubleshooting

If you cannot connect to Salesforce through Devart ODBC Driver for Salesforce, refer to the following list of common connection issues and their solutions to troubleshoot and fix the problem.

You get a "Product is not activated or has been deactivated" error

This error occurs when the Driver has not been activated or its activation is no longer valid.

• Windows: Open the DSN configuration dialog, go to the License tab, click Input Activation Key, and enter your activation key.
• macOS and Linux: In Devart ODBC Administrator, select the DSN and click Configure. On the License tab of the configuration dialog, click Input Activation Key and enter your activation key. Alternatively, run the salesforceodbcactivator utility from the Driver installation folder with your activation key.

After activation, test the connection again.

The ODBC data source is not found or the Driver is not available

If your application cannot find the DSN or Devart ODBC Driver for Salesforce, check the application and Driver bitness.

A 32-bit application cannot use a DSN created in the 64-bit ODBC Data Source Administrator, and a 64-bit application cannot use a DSN created in the 32-bit administrator.

Make sure that:

• The DSN is created in the ODBC administrator that matches your application's bitness.
• The corresponding 32-bit or 64-bit version of the Driver is installed.
• The application is configured to use the correct DSN.

The Driver cannot connect to Salesforce

If the Driver cannot reach Salesforce, verify the server address and your network settings:

• Make sure the Server field contains the correct URL: login.salesforce.com for production, test.salesforce.com for a sandbox, or the URL of your custom domain.
• Check that your firewall allows outbound HTTPS connections to Salesforce.
• If your network uses a proxy server, specify the proxy settings in the DSN or connection string.

Login or connection fails

If Salesforce is reachable but authentication fails, check the authentication settings:

• Verify that the selected authentication method matches the credentials you provide.
• OAuth 2.0: If the refresh token has expired or been revoked, click Sign in to Salesforce again to get a new token.
• User ID and Password: Verify the user ID and password. Make sure the security token is current—resetting the password in Salesforce also resets the token.
• Server-to-Server: Verify the consumer key and consumer secret, and make sure the client credentials flow is enabled and a run-as user is assigned in the app settings.
• Ensure that your Salesforce user has the API Enabled permission and access to the required objects.
• If the password is not saved in the DSN, provide it when the application prompts you.

Salesforce connection times out

If the connection to Salesforce takes too long to establish, increase Connection Timeout on the Advanced Settings tab. The default value is 60 seconds. For long-running queries, increase Query Timeout. Also, check the network connection.

Additional resources

After you install and configure Devart ODBC Driver for Salesforce, use the following resources to continue setting up and working with your connections:

• Connection string parameters — Browse the complete list of connection options for configuring authentication, proxy settings, timeouts, ODBC behavior, and other Driver settings.
• Advanced features — Learn about connection pooling, metadata caching, and foreign keys retrieval.
• Supported ODBC functions — Explore the currently supported ODBC functions.
• Using in third-party tools — Find step-by-step guides for connecting BI, reporting, analytics, and other ODBC-compatible tools to Salesforce.
• Using from programming languages — Get examples of connecting to Salesforce from Python, C#, C/C++, Go, Node.js, PHP, R, and Visual Basic.
• Documentation — Get full information on installing, configuring, and using Devart ODBC Driver for Salesforce.