Getting Started with the Salesforce Data Cloud JDBC Driver

With the Salesforce Data Cloud Java Database Connectivity (JDBC) driver, you can access and retrieve data from Data Cloud by using tools that support JDBC and Data Cloud SQL. This document provides information about setting up and configuring the Salesforce Data Cloud JDBC driver.

Before connecting to Data Cloud with the JDBC driver:

To connect to your app by using JDBC, create and configure a connected app. For basic app configuration, see Create a Connected App in Salesforce Help.

After basic app configuration, complete these steps.

  1. Enable OAuth Settings and turn on these scopes.
    • Manage user data via APIs (api): This scope allows your app to fetch a list of available Data Spaces and request a Data Cloud token.
    • Perform ANSI SQL queries on Customer Data Platform data (cdp_query_api): This scope allows your app to perform queries with the Data Cloud API.
  2. Configure authentication.
  3. Retrieve the Consumer Key and Consumer Secret values from the Manage Consumer Details page of your Connected App in the App Manager.
  4. For easier connection management, adjust your OAuth Access policies as needed. See Manage OAuth Access Policies in Salesforce Help.

Apps using the JDBC driver establish an OAuth 2.0 session with a Salesforce organization configured for Data Cloud and then use the provided access token to obtain a Data Cloud token. See Authorization Through Connected Apps and OAuth 2.0.

Alternatively, the JDBC driver can use a preobtained Data Cloud access token directly, bypassing the need to fetch one by using Salesforce OAuth access tokens.

To use the OAuth 2.0 JWT Bearer Flow, create a public and private key pair and a self-signed certificate. See OAuth 2.0 JWT Bearer Flow in Salesforce Help.

Generating a Key Pair and Certificate

  1. Open a terminal or command prompt and go to the directory where you want to store the generated files.

  2. Create a private and public key pair.

  3. Create a self-signed digital certificate from the key pair, providing your country, state, and organization name when prompted.

  4. Create a PKCS#8 private key from the key pair.

You now have keypair.key, private.key, and certificate.crt files in the folder that you selected.

Upload the certificate.crt file to the Digital Signatures section of your Connected App configuration. Provide the contents of the private.key file to the JDBC driver in the connection settings.

The OAuth 2.0 Username-Password Flow is disabled by default in connected apps. To use this flow, turn on Allow OAuth Username-Password Flows in the connected app settings. See OAuth 2.0 Username-Password Flow in Salesforce Help.

To integrate an external web app with the Salesforce API, use the OAuth 2.0 web server flow. To use the OAuth 2.0 Refresh Token Flow, select the Perform requests any time (refresh_token, offline access) scope. See OAuth 2.0 Web Server Flow in Salesforce Help.

Configure the driver by using a connection URL combined with Java properties. The URL format is jdbc:salesforce-datacloud://<Salesforce Org API or Login Domain Name>.

For example, if your Salesforce organization URL is https://mycompany.my.salesforce.com, the JDBC connection URL is jdbc:salesforce-datacloud://mycompany.my.salesforce.com. For the JWT Bearer Flow, use the Salesforce login domain name, for example, jdbc:salesforce-datacloud://login.salesforce.com. For all other OAuth flows, use your Salesforce organization’s API domain name in the connection URL.

During connection setup, provide these properties for your OAuth flow.

  • clientId: Consumer Key from your Connected App
  • clientSecret: Consumer Secret from your Connected App
  • privateKey: Contents of the private key file (PEM format)
  • userName: Username for the account.
  • clientId: Consumer Key from your Connected App
  • clientSecret: Consumer Secret from your Connected App
  • refreshToken: Refresh token obtained during an OAuth flow
  • userName: Username associated with the refreshToken
  • dataspace: Data Space for queries. Default: default.
  • maxRetries: Number of authentication request retries. Default: 3
  • User-Agent: This value identifies your application and can help Salesforce Support with debugging. It must be a valid product component as defined in RFC7231, including a version component. Format: salesforce-datacloud-jdbc/version.