|
1 | | -# README |
| 1 | +# Salesforce DataCloud JDBC Driver |
2 | 2 |
|
3 | | -A repo containing all the basic file templates and general guidelines for any open source project at Salesforce. |
| 3 | +With the Salesforce Data Cloud JDBC driver you can efficiently query millions of rows of data with low latency, and perform bulk data extractions. |
| 4 | +This driver is read-only and forward-only. |
| 5 | +It requires Java 11 or greater. |
| 6 | + |
| 7 | + |
| 8 | +## Getting started |
| 9 | + |
| 10 | +To add the driver to your project, add the following Maven dependency: |
| 11 | + |
| 12 | +```xml |
| 13 | +<dependency> |
| 14 | + <groupId>com.salesforce.datacloud</groupId> |
| 15 | + <artifactId>jdbc</artifactId> |
| 16 | + <version>${jdbc.version}</version> |
| 17 | +</dependency> |
| 18 | +``` |
| 19 | + |
| 20 | +The class name for this driver is: |
| 21 | + |
| 22 | +``` |
| 23 | +com.salesforce.datacloud.jdbc.DataCloudJDBCDriver |
| 24 | +``` |
| 25 | + |
| 26 | +## Building the driver: |
| 27 | + |
| 28 | +Use the following command to build and test the driver: |
| 29 | + |
| 30 | +```shell |
| 31 | +mvn clean install |
| 32 | +``` |
4 | 33 |
|
5 | 34 | ## Usage |
6 | 35 |
|
7 | | -It's required that all files must be placed at the top level of your repository. |
| 36 | +### Connection string |
| 37 | + |
| 38 | +Use `jdbc:salesforce-datacloud://login.salesforce.com` |
| 39 | + |
| 40 | +### JDBC Driver class |
| 41 | + |
| 42 | +Use `com.salesforce.datacloud.jdbc.DataCloudJDBCDriver` as the driver class name for the JDBC application. |
| 43 | + |
| 44 | +### Authentication |
| 45 | + |
| 46 | +We support three of the [OAuth authorization flows][oauth authorization flows] provided by Salesforce. |
| 47 | +All of these flows require a connected app be configured for the driver to authenticate as, see the documentation here: [connected app overview][connected app overview]. |
| 48 | +Set the following properties appropriately to establish a connection with your chosen OAuth authorization flow: |
| 49 | + |
| 50 | +| Parameter | Description | |
| 51 | +|--------------|----------------------------------------------------------------------------------------------------------------------| |
| 52 | +| user | The login name of the user. | |
| 53 | +| password | The password of the user. | |
| 54 | +| clientId | The consumer key of the connected app. | |
| 55 | +| clientSecret | The consumer secret of the connected app. | |
| 56 | +| privateKey | The private key of the connected app. | |
| 57 | +| coreToken | OAuth token that a connected app uses to request access to a protected resource on behalf of the client application. | |
| 58 | +| refreshToken | Token obtained from the web server, user-agent, or hybrid app token flow. | |
| 59 | + |
| 60 | + |
| 61 | +#### username and password authentication: |
| 62 | + |
| 63 | +The documentation for username and password authentication can be found [here][username flow]. |
| 64 | + |
| 65 | +To configure username and password, set properties like so: |
| 66 | + |
| 67 | +```java |
| 68 | +Properties properties = new Properties(); |
| 69 | +properties.put("user", "${userName}"); |
| 70 | +properties.put("password", "${password}"); |
| 71 | +properties.put("clientId", "${clientId}"); |
| 72 | +properties.put("clientSecret", "${clientSecret}"); |
| 73 | +``` |
| 74 | + |
| 75 | +#### jwt authentication: |
| 76 | + |
| 77 | +The documentation for jwt authentication can be found [here][jwt flow]. |
| 78 | + |
| 79 | +Instuctions to generate a private key can be found [here](#generating-a-private-key-for-jwt-authentication) |
| 80 | + |
| 81 | +```java |
| 82 | +Properties properties = new Properties(); |
| 83 | +properties.put("privateKey", "${privateKey}"); |
| 84 | +properties.put("clientId", "${clientId}"); |
| 85 | +properties.put("clientSecret", "${clientSecret}"); |
| 86 | +``` |
| 87 | + |
| 88 | +#### refresh token authentication: |
| 89 | + |
| 90 | +The documentation for refresh token authentication can be found [here][refresh token flow]. |
| 91 | + |
| 92 | +```java |
| 93 | +Properties properties = new Properties(); |
| 94 | +properties.put("coreToken", "${coreToken}"); |
| 95 | +properties.put("refreshToken", "${refreshToken}"); |
| 96 | +properties.put("clientId", "${clientId}"); |
| 97 | +properties.put("clientSecret", "${clientSecret}"); |
| 98 | +``` |
| 99 | + |
| 100 | +### Connection settings |
| 101 | + |
| 102 | +See this page on available [connection settings][connection settings]. |
| 103 | +These settings can be configured in properties by using the prefix `serverSetting.` |
| 104 | + |
| 105 | +For example, to control locale set the following property: |
| 106 | + |
| 107 | +```java |
| 108 | +properties.put("serverSetting.lc_time", "en_US"); |
| 109 | +``` |
| 110 | + |
| 111 | +--- |
| 112 | + |
| 113 | +### Generating a private key for jwt authentication |
| 114 | + |
| 115 | +To authenticate using key-pair authentication you'll need to generate a certificate and register it with your connected app. |
| 116 | + |
| 117 | +```shell |
| 118 | +# create a key pair: |
| 119 | +openssl genrsa -out keypair.key 2048 |
| 120 | +# create a digital certificate, follow the prompts: |
| 121 | +openssl req -new -x509 -nodes -sha256 -days 365 -key keypair.key -out certificate.crt |
| 122 | +# create a private key from the key pair: |
| 123 | +openssl pkcs8 -topk8 -nocrypt -in keypair.key -out private.key |
| 124 | +``` |
| 125 | + |
| 126 | +### Optional configuration |
| 127 | + |
| 128 | +- `dataspace`: The data space to query, defaults to "default" |
| 129 | +- `User-Agent`: The User-Agent string identifies the JDBC driver and, optionally, the client application making the database connection. <br /> |
| 130 | + By default, the User-Agent string will end with "salesforce-datacloud-jdbc/{version}" and we will prepend any User-Agent provided by the client application. <br /> |
| 131 | + For example: "User-Agent: ClientApp/1.2.3 salesforce-datacloud-jdbc/1.0" |
| 132 | + |
| 133 | + |
| 134 | +### Usage sample code |
| 135 | + |
| 136 | +```java |
| 137 | +public static void executeQuery() throws ClassNotFoundException, SQLException { |
| 138 | + Class.forName("com.salesforce.datacloud.jdbc.DataCloudJDBCDriver"); |
| 139 | + |
| 140 | + Properties properties = new Properties(); |
| 141 | + properties.put("user", "${userName}"); |
| 142 | + properties.put("password", "${password}"); |
| 143 | + properties.put("clientId", "${clientId}"); |
| 144 | + properties.put("clientSecret", "${clientSecret}"); |
| 145 | + |
| 146 | + try (var connection = DriverManager.getConnection("jdbc:salesforce-datacloud://login.salesforce.com", properties); |
| 147 | + var statement = connection.createStatement()) { |
| 148 | + var resultSet = statement.executeQuery("${query}"); |
| 149 | + |
| 150 | + while (resultSet.next()) { |
| 151 | + // Iterate over the result set |
| 152 | + } |
| 153 | + } |
| 154 | +} |
| 155 | +``` |
| 156 | + |
| 157 | +## Generated assertions |
| 158 | + |
| 159 | +Some of our classes are tested using assertions generated with [the assertj assertions generator][assertion generator]. |
| 160 | +Due to some transient test-compile issues we experienced, we checked in generated assertions for some of our classes. |
| 161 | +If you make changes to any of these classes, you will need to re-run the assertion generator to have the appropriate assertions available for that class. |
| 162 | + |
| 163 | +To find examples of these generated assertions, look for files with the path `**/test/**/*Assert.java`. |
| 164 | + |
| 165 | +To re-generate these assertions execute the following command: |
| 166 | + |
| 167 | +```shell |
| 168 | +mvn assertj:generate-assertions |
| 169 | +``` |
8 | 170 |
|
9 | | -> **NOTE** Your README should contain detailed, useful information about the project! |
10 | 171 |
|
| 172 | +[oauth authorization flows]: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_flows.htm&type=5 |
| 173 | +[username flow]: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_username_password_flow.htm&type=5 |
| 174 | +[jwt flow]: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm&type=5 |
| 175 | +[refresh token flow]: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&type=5 |
| 176 | +[connection settings]: https://tableau.github.io/hyper-db/docs/hyper-api/connection#connection-settings |
| 177 | +[assertion generator]: https://joel-costigliola.github.io/assertj/assertj-assertions-generator-maven-plugin.html#configuration |
| 178 | +[connected app overview]: https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm&type=5 |
0 commit comments