Skip to main content
The JDBC Driver and command-line interface (CLI) enable you to connect to Ocient using a JDBC connection. Ensure that you meet the prerequisites before using the Ocient JDBC Driver. Then, invoke the CLI program, configure options, and connect to a database using the driver. You can also use the data extract tool to extract a result set to delimited files in the target location. For details about data extracting, see Data Extract Tool. For a list of commands available in the JDBC CLI, see Commands Supported by the Ocient JDBC CLI Program.

Prerequisites

This software is required for the JDBC driver.

Driver Features

The Ocient JDBC connector supports these features as of the current version.

Invoke the Ocient JDBC CLI Program

If your system meets all the necessary prerequisites, you can run the JDBC CLI by using the Ocient JDBC JAR file. To do this, follow these steps.
1
Go to the Ocient repository for all JDBC versions. For more information on which version to pick, see the Version Compatibility page.
2
For the JDBC version you want to use, download the JAR file with dependencies. This JAR file follows the format: ocient-jdbc4-<version number>-jar-with-dependencies.jar.Move this JAR file to the directory where your Ocient System is installed.
3
From the shell terminal, run this command to launch the JDBC CLI.
Shell
This example runs JDBC version 2.10.
Shell
4
After launching, the JDBC CLI prompts you to enter your username and password.
Shell
The interface changes to the Ocient CLI.
Shell
5
Connect to your system from the JDBC using a connection string.Assuming the standard port 4050, a self-signed certificate, and the SQL Node IP address 10.10.1.1, you can connect to the system database with the following connecting string.
Shell
The CLI responds with a connection message.
Shell
Now that you are connected to your system, you can execute any queries or commands.
For Java version 1.8.0_144, download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8.

JDBC CLI Configuration Options

The JDBC CLI reads a configuration file consisting of key-value pairs located at ~/.ocient-cli-configuration with this format.
Shell
The JDBC CLI supports these options. For supported commands, see Commands Supported by the Ocient JDBC CLI Program.

Run a Transaction in the JDBC CLI

The Ocient JDBC CLI supports multi-statement transactions using SQL statements. To begin a transaction, execute the SET AUTOCOMMIT OFF SQL statement, and then end the transaction with the COMMIT or ROLLBACK statements. A query within the transaction reads uncommitted rows that the same connection has inserted. This example disables autocommit, inserts two rows into the public.txn_demo table, counts the rows in the table, and commits the transaction. Next, the example inserts two more rows in the table and counts the rows. Then, the example runs a ROLLBACK command to roll back the changes, and counts the rows again.
SQL

Use the Ocient JDBC Driver in Java Programs

First, you must load the Ocient driver class with this statement in a Java program using the JDBC driver.
Java
The driver class is located in the JDBC driver JAR file named ocient-jdbc4.jar and must be available in the CLASSPATH defined for the program.

Connect Using JDBC

The Ocient JDBC driver supports connection properties that can be supplied using the CONNECT command in the JDBC CLI or as a properties object passed in a Java application. JDBC URL Example This connection string includes various connection properties that trail the login credentials.
Shell
Java DriverManager Example Alternatively, you can use the DriverManager class to provide connection properties if you are using a JDBC connection as part of a Java application.
Java

Supported JDBC Connection Properties

The JDBC driver supports these connection parameters.

JVM System Properties

The Ocient JDBC driver supports system properties that control driver-wide behavior. Unlike connection properties, JVM system properties apply globally to all connections within the JVM. To set JVM properties, use the -D flag from the java command line. The system reads these properties once when the driver initializes and cannot change them at runtime. Example This example launches the JDBC CLI with the memory throttle disabled. There is no space between -D and the property name.
Shell

Supported JVM System Properties

JVM system properties are not part of the JDBC connection URL or the Properties object the system passes to DriverManager.getConnection(). You must set them at the java command line.
Set the com.ocient.jdbc.rs.disable-memory-throttle property to true only when you have verified that your application has sufficient heap headroom or when the throttle interferes with the expected workload behavior. Disabling the throttle can cause the OutOfMemoryError error if the JVM heap is exhausted.

JDBC Bulk Loading

For very large batches, the Ocient JDBC driver provides a high-speed bulk load path. When you enable bulk loading, the driver bypasses the standard multi-row insert operation and instead stages the batch data in the JSON Lines format and loads it through a temporary, system-generated Ocient pipeline. The driver supports two transport modes for staging data.
  • SSH/SFTP (default) — The driver opens an SSH connection to a Loader Node and writes JSON data files directly to the node file system using SFTP.
  • S3 — The driver uploads JSON data files to an S3-compatible bucket. The Ocient System then reads the staged files from S3 through standard pipeline mechanics. This mode eliminates the requirement for SSH access between the client and the Loader Nodes.
Set the bulkLoadMode connection parameter to select the transport mode. The default value is ssh.

Configuration

Follow these steps to configure bulk loading in your JDBC driver. Enable Bulk Loading The JDBC driver disables bulk loading by default. To enable it, you must meet these conditions.
  • Set the enableBulkLoad connection parameter to true.
  • Use a parameterized INSERT statement that uses placeholders for values, e.g., INSERT INTO customers (id, name, status) VALUES (?, ?, ?). For details, see Set Up Parameterized Insert Statements.
  • The total number of rows in the batch group meets or exceeds the bulkLoadThreshold parameter.
For recommended configuration settings for workloads, see Bulk Loading Best Practices.
Choose a Transport Mode Set the bulkLoadMode connection parameter to select how the driver stages data for the pipeline. The supported values are ssh (default) and s3. SSH Mode Configuration SSH mode requires passwordless SSH access from the client to all Loader Nodes in the cluster. To point the driver to your private SSH key file, set the bulkLoadSshKeyPath connection parameter. The client application must be able to read this file. The driver automatically discovers available Loader Nodes by querying the sys.nodes and sys.service_roles system catalog tables. S3 Mode Configuration The S3 mode stages data in an S3-compatible object store (such as S3 or ) and does not require SSH access to the Loader Nodes. When you select the S3 mode, you must provide the following required connection parameters. You can also set optional S3 parameters to control the region, key prefix, path-style access, multipart upload behavior, upload concurrency, and API call timeout. For the full list of S3 parameters and their defaults, see the Supported JDBC Connection Properties table. The driver uploads JSON data chunks to the staging bucket, generates a CREATE TRANSACTIONAL PIPELINE SOURCE S3 SQL statement that points the Ocient System to the staged objects, and monitors the pipeline to completion. After the pipeline finishes, the driver deletes the staged objects from S3 and drops the pipeline. On failure, this cleanup occurs only when you set the bulkLoadCleanupOnFailure parameter to true (the default).
The S3 access key identifier and secret access key are embedded in the pipeline DDL so that the Ocient System can read the staged objects. The pipeline is transactional and the driver drops it immediately after use. The Spark connector redacts credentials from its logs.
Data Type Mapping The JDBC driver supports all standard scalar types. For complex types, Java SQL STRUCT (java.sql.Struct) types load as Ocient TUPLE types, and Java ARRAY (java.sql.Array) types load as Ocient ARRAY types.

Set Up Parameterized INSERT Statements

These steps demonstrate how to use a single parameterized INSERT statement using the Java PreparedStatement class. The parameterized statement binds different values for each row.
1
Create the PreparedStatement object ps with ? placeholders.
Java
2
Bind parameter values by position.
Java
3
Execute a single insert.
Java
Or, add multiple rows as a batch.
Java
4
Close the resources.
Java

Connection Encryption (SSL/TLS)

The JDBC driver can use SSL/TLS to connect to Ocient, causing all traffic to be encrypted. Specify the tls property on the connect statement to enable TLS support. The tls property supports these values. unverified Traffic on the connection is encrypted, but no verification is done on the certificate received from the Ocient System. on Traffic is encrypted, and the JDBC client must be able to verify the certificate received from the Ocient System. The TLS on mode requires that the client knows the Certificate Authority that signed the certificate provided by the Ocient System. Typically, this mode requires either that the certificate is signed by a well-known certificate authority, or the Certificate Authority certificate has been imported into the truststore of the Java system. The Java keytool utility is used to manipulate a Java truststore. Secure Connections Using TLS discusses how you can configure user-defined certificates for the Ocient System.

Sample Java Program Using the Ocient JDBC Driver

This sample program demonstrates how to utilize the Ocient JDBC driver to establish a connection to a database, construct a prepared SQL statement, execute the query, and iterate through the result set.
Java
For supported classes and methods, see JDBC Classes and Methods.

Run a Transaction Using the Ocient JDBC Driver

To run a multi-statement transaction with the Ocient JDBC driver in a Java program, disable the autocommit mode using setAutoCommit(false), and then call the commit() or rollback() methods. For transactions, autocommit mode is on by default. Ensure that you execute SQL statements that are supported by transactions. Otherwise, the database throws an error. For a list of supported statements, see Transactions. This example code connects to a sample database and creates the public.txn_demo table. Then, the code inserts two rows and displays the row count in the table. The code commits the INSERT statements and re-runs the row count. This code inserts two more rows and displays a row count. Then, the example rolls back the transaction and displays a row count. Finally, the code enables the autocommit mode.
Java
Connect Using JDBC Data Extract Tool Commands Supported by the Ocient JDBC CLI Program JDBC Classes and Methods.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
Last modified on July 2, 2026