Skip to content

Commit d546a15

Browse files
draliatpdraliatp
authored
Update README.md
1 parent d908fdd commit d546a15

File tree

1 file changed

+75
-78
lines changed

1 file changed

+75
-78
lines changed

‎README.md

+75-78
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
# Salesforce DataCloud JDBC Driver
1+
# Salesforce Data Cloud JDBC Driver
22

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, forward-only, and requires Java 8 or greater. It uses the new [Data Cloud Query API SQL syntax](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql-context.html).
3+
This driver allows you to efficiently query large datasets in Salesforce Data Cloud with low latency and perform bulk data extractions. It's read-only, forward-only, and requires Java 8 or later. The driver uses the Data Cloud Query API SQL syntax (see [Data Cloud Query API SQL syntax](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql-context.html) for details).
54

5+
## Getting Started
66

7-
## Getting started
7+
### Maven Dependency
88

9-
To add the driver to your project, add the following Maven dependency:
9+
To use the driver in your Maven project, add the following to your `pom.xml`:
1010

1111
```xml
1212
<dependency>
@@ -16,52 +16,53 @@ To add the driver to your project, add the following Maven dependency:
1616
</dependency>
1717
```
1818

19-
The class name for this driver is:
19+
Replace `${jdbc.version}` with the actual version of the driver. It's good practice to manage this version in a properties section of your pom.xml.
2020

21-
```
22-
com.salesforce.datacloud.jdbc.DataCloudJDBCDriver
23-
```
21+
### Driver Class
2422

25-
## Building the driver:
23+
The driver class name is: `com.salesforce.datacloud.jdbc.DataCloudJDBCDriver`
2624

27-
Use the following command to build and test the driver:
25+
## Building the Driver
2826

29-
```shell
27+
To build and test the driver, run:
28+
29+
```bash
3030
mvn clean install
3131
```
3232

3333
## Usage
3434

35-
### Connection string
35+
### Connection String
3636

37-
Use `jdbc:salesforce-datacloud://login.salesforce.com`
37+
The connection string format is: `jdbc:salesforce-datacloud://login.salesforce.com`
3838

39-
### JDBC Driver class
39+
### Driver Class (Reiterated)
4040

41-
Use `com.salesforce.datacloud.jdbc.DataCloudJDBCDriver` as the driver class name for the JDBC application.
41+
Use `com.salesforce.datacloud.jdbc.DataCloudJDBCDriver` when loading the driver in your JDBC application. For example:
4242

43-
### Authentication
43+
```java
44+
Class.forName("com.salesforce.datacloud.jdbc.DataCloudJDBCDriver");
45+
```
4446

45-
We support three of the [OAuth authorization flows][oauth authorization flows] provided by Salesforce.
46-
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].
47-
Set the following properties appropriately to establish a connection with your chosen OAuth authorization flow:
47+
### Authentication
4848

49-
| Parameter | Description |
50-
|--------------|----------------------------------------------------------------------------------------------------------------------|
51-
| user | The login name of the user. |
52-
| password | The password of the user. |
53-
| clientId | The consumer key of the connected app. |
54-
| clientSecret | The consumer secret of the connected app. |
55-
| privateKey | The private key of the connected app. |
56-
| coreToken | OAuth token that a connected app uses to request access to a protected resource on behalf of the client application. |
57-
| refreshToken | Token obtained from the web server, user-agent, or hybrid app token flow. |
49+
The driver supports several OAuth authorization flows provided by Salesforce (see [OAuth authorization flows](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_flows.htm&type=5)). You'll need to configure a connected app (see [Connected App Overview](https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm&type=5)).
5850

51+
The following table outlines the properties for each flow:
5952

60-
#### username and password authentication:
53+
| Property | Description | Authentication Flow |
54+
| -------------- | ------------------------------ | -------------------------------- |
55+
| `user` | Salesforce username. | Username/Password |
56+
| `password` | Salesforce password. | Username/Password |
57+
| `clientId` | Connected app consumer key. | All |
58+
| `clientSecret` | Connected app consumer secret. | Username/Password, Refresh Token |
59+
| `privateKey` | Connected app private key. | JWT |
60+
| `coreToken` | OAuth token. | Refresh Token |
61+
| `refreshToken` | Refresh token. | Refresh Token |
6162

62-
The documentation for username and password authentication can be found [here][username flow].
63+
#### Username/Password Authentication
6364

64-
To configure username and password, set properties like so:
65+
See [Username/Password Flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_username_password_flow.htm&type=5) for more information. Example:
6566

6667
```java
6768
Properties properties = new Properties();
@@ -71,11 +72,9 @@ properties.put("clientId", "${clientId}");
7172
properties.put("clientSecret", "${clientSecret}");
7273
```
7374

74-
#### jwt authentication:
75-
76-
The documentation for jwt authentication can be found [here][jwt flow].
75+
#### JWT Authentication
7776

78-
Instructions to generate a private key can be found [here](#generating-a-private-key-for-jwt-authentication)
77+
See [JWT Flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm&type=5). For generating a private key, see [Generating a Private Key](#generating-a-private-key-for-jwt-authentication). Example:
7978

8079
```java
8180
Properties properties = new Properties();
@@ -84,9 +83,9 @@ properties.put("clientId", "${clientId}");
8483
properties.put("clientSecret", "${clientSecret}");
8584
```
8685

87-
#### refresh token authentication:
86+
#### Refresh Token Authentication
8887

89-
The documentation for refresh token authentication can be found [here][refresh token flow].
88+
See [Refresh Token Flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&type=5). Example:
9089

9190
```java
9291
Properties properties = new Properties();
@@ -96,77 +95,75 @@ properties.put("clientId", "${clientId}");
9695
properties.put("clientSecret", "${clientSecret}");
9796
```
9897

99-
### Connection settings
98+
### Connection Settings
10099

101-
See this page on available [connection settings][connection settings].
102-
These settings can be configured in properties by using the prefix `querySetting.`
103-
104-
For example, to control locale set the following property:
100+
Additional connection settings are available (see [Connection Settings](https://tableau.github.io/hyper-db/docs/hyper-api/connection#connection-settings)). Prefix properties with `querySetting.`. For example, to set the locale:
105101

106102
```java
107103
properties.put("querySetting.lc_time", "en_US");
108104
```
109105

110-
---
111-
112-
### Generating a private key for jwt authentication
106+
## Generating a Private Key for JWT Authentication <a name="generating-a-private-key-for-jwt-authentication"></a>
113107

114-
To authenticate using key-pair authentication you'll need to generate a certificate and register it with your connected app.
108+
For JWT authentication, you need a certificate registered with your connected app.
115109

116-
```shell
117-
# create a key pair:
110+
```bash
111+
# Create a key pair:
118112
openssl genrsa -out keypair.key 2048
119-
# create a digital certificate, follow the prompts:
113+
114+
# Create a digital certificate:
120115
openssl req -new -x509 -nodes -sha256 -days 365 -key keypair.key -out certificate.crt
121-
# create a private key from the key pair:
116+
117+
# Create the private key:
122118
openssl pkcs8 -topk8 -nocrypt -in keypair.key -out private.key
123119
```
124120

125-
### Optional configuration
121+
## Optional Configuration
126122

127-
- `dataspace`: The data space to query, defaults to "default"
128-
- `User-Agent`: The User-Agent string identifies the JDBC driver and, optionally, the client application making the database connection. <br />
129-
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 />
130-
For example: "User-Agent: ClientApp/1.2.3 salesforce-datacloud-jdbc/1.0"
123+
- `dataspace`: The data space to query (defaults to "default").
124+
- `User-Agent`: Identifies the JDBC driver and client application. Defaults to `salesforce-datacloud-jdbc/{version}`. You can prepend your application's User-Agent string. Example: `User-Agent: ClientApp/1.2.3 salesforce-datacloud-jdbc/1.0`
131125

132-
133-
### Usage sample code
126+
## Usage Example
134127

135128
```java
136-
public static void executeQuery() throws ClassNotFoundException, SQLException {
137-
Class.forName("com.salesforce.datacloud.jdbc.DataCloudJDBCDriver");
129+
import java.sql.*;
130+
import java.util.Properties;
131+
132+
public class DataCloudQuery {
138133

139-
Properties properties = new Properties();
140-
properties.put("user", "${userName}");
141-
properties.put("password", "${password}");
142-
properties.put("clientId", "${clientId}");
143-
properties.put("clientSecret", "${clientSecret}");
134+
public static void executeQuery() throws ClassNotFoundException, SQLException {
135+
Class.forName("com.salesforce.datacloud.jdbc.DataCloudJDBCDriver");
144136

145-
try (var connection = DriverManager.getConnection("jdbc:salesforce-datacloud://login.salesforce.com", properties);
146-
var statement = connection.createStatement()) {
147-
var resultSet = statement.executeQuery("${query}");
137+
Properties properties = new Properties();
138+
properties.put("user", "${userName}");
139+
properties.put("password", "${password}");
140+
properties.put("clientId", "${clientId}");
141+
properties.put("clientSecret", "${clientSecret}");
148142

149-
while (resultSet.next()) {
150-
// Iterate over the result set
143+
try (Connection connection = DriverManager.getConnection("jdbc:salesforce-datacloud://login.salesforce.com", properties);
144+
Statement statement = connection.createStatement();
145+
ResultSet resultSet = statement.executeQuery("${query}")) {
146+
147+
while (resultSet.next()) {
148+
// Process the result set. Example:
149+
System.out.println(resultSet.getString(1)); // Assuming a string in the first column
150+
}
151151
}
152152
}
153153
}
154154
```
155155

156-
## Generated assertions
157-
158-
Some of our classes are tested using assertions generated with [the assertj assertions generator][assertion generator].
159-
Due to some transient test-compile issues we experienced, we checked in generated assertions for some of our classes.
160-
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.
156+
Remember to replace placeholders like `${userName}` and `${query}` with your actual values. Consider using parameterized queries to prevent SQL injection vulnerabilities.
161157

162-
To find examples of these generated assertions, look for files with the path `**/test/**/*Assert.java`.
158+
## Generated Assertions
163159

164-
To re-generate these assertions execute the following command:
160+
Some classes use generated assertions (from [AssertJ Assertions Generator](https://joel-costigliola.github.io/assertj/assertj-assertions-generator-maven-plugin.html#configuration)). If you modify these classes, regenerate the assertions:
165161

166-
```shell
162+
```bash
167163
mvn assertj:generate-assertions
168164
```
169165

166+
Find examples in `**/test/**/*Assert.java`.
170167

171168
[oauth authorization flows]: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_flows.htm&type=5
172169
[username flow]: https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_username_password_flow.htm&type=5

0 commit comments

Comments
 (0)