Introduction

 

Reliersoft’s Salesforce JDBC driver is designed to work immediately with tools such as DbVisualizer and Squirrel. If you prefer, you may also use the driver in a Java IDE such as Eclipse. It is intended to provide SQL support for Salesforce.com (as opposed to SOQL), via a re-writing engine and via multi-pass execution where necessary. It also provides data manipulation language (DML) support with its support for SQL UPDATE, DELETE, INSERT and MERGE statements.

Using the driver with DbVisualizer
Using the driver with Squirrel
Using the driver in an IDE
Optional connection string parameters

 

Using the driver with DbVisualizer

 

1) In DbVisualizer, go to the driver manager (Tools in the top menu, then Driver Manager…) and click the “Create a new driver” button.
2) Enter any name you wish. The URL Format can remain empty. In the “Driver File Paths” section, open up the driver.
3) Once the driver has been added, in the main screen of DbVisualizer, you may use the following settings to connect to Salesforce (entering your Salesforce Userid and Password):

The settings should be as follows:
Database Type: Generic
Database URL: jdbc:sforce://login.salesforce.com?anyoptionalparameters

 

Using the driver with Squirrel

 

1) In the Drivers tab on the left of the screen, click the plus button to add a new driver. Enter any name you wish. Click the “Extra Class Path” tab, and the “Add” button. Locate the driver on your computer. Click the “List Drivers” button. You should see com.reliersoft.sforce.jdbc.Driver in the Class Name at the bottom.
2) In the “Example URL” field, enter “jdbc:sforce://login.salesforce.com” and click OK.
3) In the “Aliases” tab, click the plus button to add a new alias. Enter any name you wish. Select the driver, and enter your Salesforce User Name and Password. Click OK.
4) Double click on the alias name and click “Connect” to connect to Salesforce. Once successfully connected, Salesforce information will be shown.

 

Using the driver in an IDE

 

In any Java IDE such as Eclipse, you may add the driver to your build path and connect through your Java application. Below is an example:

public class main {
 public static void main(String[] args) {
 try {
 Class.forName("com.reliersoft.sforce.jdbc.Driver");
 } catch (ClassNotFoundException e) {
 e.printStackTrace();
 return;
 }
 try { 
 Connection connection = null;
 String salesforceUsername = "";
 String salesforcePassword = ""; 
 connection = DriverManager.getConnection(
 "jdbc:sforce://login.salesforce.com",salesforceUsername,salesforcePassword); 
 System.out.println("Connected to Salesforce.");
 } catch (SQLException e) {
 e.printStackTrace();
 return;
 }
 }
}

Optional connection string parameters

 

Connection string parameters are parameters you can put at the end of the connect URL (jdbc:sforce://login.salesforce.com). For example, using the connection string parameter “local” might look like “jdbc:sforce://login.salesforce.com?locale=en_US“. If you are using more than one parameter, separate them with &, for example “jdbc:sforce://login.salesforce.com?locale=en_US&acceptAllCertificates=true”

Below is a list of parameters you can use.

locale
Example value: en_US
Default value: en_US
The language to use for the display of metadata (table, column and related information). This does not affect the display of time-of-day (timezones) and currency (monetary) amount displays, which are determined by the user settings.

proxyHost
Example value: myproxy.com
Default value: [system settings]
If a specific proxy needs to be specified, it can be entered using this parameter, providing either an IPv4 address, IPv6 address or a hostname.

proxyPort
Example value: 8080
Default value: [system settings]
If a specific proxy server is being specified, the TCP/IP port number it is reachable on.

proxyUser
Example value: fred
Default value: (none)
If a specific proxy server is being specified and requires an explicit authentication, the username to use to authenticate with the proxy server.

proxyPassword
Example value: pASS
Default value: (none)
If a specific proxy server is being specified and requires an explicit authentication, the password to use to authenticate with the proxy server.

fetchSize
Example value: 1000
Default value: 2000
The fetch size to use in SOQL calls to SFDC. Valid values are between 1 and 2000, according to Salesforce limits. The maximum value is 2000 however Salesforce may use a lower value for very wide objects. The driver may multi-thread requests for chunks to impove fetch performance.

batchSize
Example value: 400
Default value: 200
For DML operations, this is the maximum number of operations per submission to Salesforce back-end. For example, DELETE FROM [object], where object has 10,000 records and the batchSize is 200, will result in 20 submissions to Salesforce. Additionally, if JDBC batch methods are used, then this is the limit prior to submitting the batch.
For example if the batch size is 200 and the following code is performed for 10,000 inserts, there will be 50 request messages sent to Salesforce.

public static void main(String[] args) {
 Connection conn;
 Statement stmt;
 props = new Properties();
 props.setProperty("user","Salesforce.User@org.com");
 props.setProperty("password","abcdef");
 url = "jdbc:sforce://test.salesforce.com";
 try {
 conn = DriverManager.getConnection(url, props);
 stmt = conn.createStatement();
 sql="insert into Account (name) values ('hello world!')";
 
 // insert this record ten thousand times
 for ( int i = 0; i < 10000; i++) {
 stmt.addBatch(sql);
 }
 }
 catch (Exception e) {
 e.printStackTrace();
 }
}

Note that in some cases, where there is a large overhead in relation to an operation, this value may need to be reduced to very low values in order not to exceed Salesforce API limits.

failIfFieldTooLong
Example value: false
Default value: true
The behaviour if an input field is too large for its target field. If this is set to false, then a value too long to fit a field will be truncated to fit into the field. If this is set to true, it will error instead. The default is true (to fail the record).

stopOnErrors
Example value: true
Default value: false
If an error is encountered during a DML operation, then if this is set to true, an exception will be thrown and there will be no further requests sent to SFDC in relation to that statement. If set to false (the default), execution will continue after the first error. For example, some records may fail an update and some may not.

setFieldsToNullInUpdates
Example value: false
Default value: true
If a value for update is null or an empty string, and this has been set to false, the value will not be changed. The default value is true, meaning that by default all updates are performed including those that set a value to nothing.
Note, Salesforce treats nulls and empty strings as the same. Consequently, Salesforce JDBC driver also treats null and empty string as equivalent.

performHardDeletes
Example value: true
Default value: false
When set to true, the default behaviour of moving deleted records to the recycle bin is replaced by a hard delete, whereby records are removed from the recycle bin immediately after a DELETE statement is performed. This may be necessary if Data Usage limits have been reached.

setFieldsToNullInUpserts
Example value: false
Default value: true
When set to true, this attribute will set fields to null if the value specified or resolved in an UPSERT SQL statement comes out to null (or empty string, which is equivalent in the context of Salesforce JDBC).
This behaviour can be overridden at the SQL statement level by the optional IGNORE NULL and INCLUDE NULL clauses of UPSERT.
Note, Salesforce treats nulls and empty strings as the same. Consequently, Salesforce JDBC driver also treats null and empty string as equivalent.

acceptAllCertificates
Example value: true
Default value: false
If set to true, SFDC certificate is not validated. Default false.

readTimeout
Example value: 20000
Default value: 30000
The time to wait for a resonse from SFDC before timing out, in milliseconds. If waiting more than this time for a response from SFDC, a timeout exception is thrown. Default is 30 seconds.

connectTimeout
Example value: 60000
Default value: 30000
The timeout value applicable when connecting, in milliseconds. If waiting more than this time for a response from SFDC, a timeout exception is thrown. Default is 30 seconds.
timeout
Example value: 15000
Default value: (none)
Timeout value for both readTimeout and connectTimeout.

token
Example value: d8OVlZ7hnPefP4mLT1x7F4Sy0
Default value: (none)
Salesforce security token in relation to the user account (User settings -> Reset my security token). Alternatively, the security token can be appended to the password (which is equivalent).

api
Example value: 36.0
Default value: 35.0
Target back-end API version. Valid values are of the form [integer].
Note, API versions much younger or older than the driver release date, may not be compatible with the driver. To resolve this, check the website for a new version of the driver. The current driver version can be found with getDriverVersion().
The default API version may change with newer releases of the driver. To check the API endpoint version being used, refer to getDatabaseProductVersion().

schema
Example value: MYSANDBOX
Default value: (none)
Sets a schema name for all database metadata to be presented under. Default is no schema.