Skip to content

Connection.md

Latest commit

 

History

History
119 lines (90 loc) · 8.04 KB

Connection.md

File metadata and controls

119 lines (90 loc) · 8.04 KB
Raw

JDBC Driver

Databend JDBC driver access databend distributions or databend cloud through [REST API]{https://databend.rs/doc/integrations/api/rest}. To use jdbc documentation, you could add the following dependency from maven central

<dependency>
    <groupId>com.databend</groupId>
    <artifactId>databend-jdbc</artifactId>
    <version>|version|</version>
</dependency>

Driver Name

The driver class name is com.databend.jdbc.DatabendDriver. Most JDBC drivers are automatically loaded by the DriverManager class. However, if you are using a JDBC driver that is not automatically loaded, you can load it by calling the Class.forName method.

Connecting

The following JDBC URL formats are supported

jdbc:databend://host:port
jdbc:databend://user:password@host:port
jdbc:databend://host:port/database
jdbc:databend://user:password@host:port/database

For example, the following URL connects to databend host on your local machine with host 0.0.0.0 port 8000 and database hello_databend with username databend password secret

jdbc:databend://databend:secret@0.0.0.0:8000/hello_databend

The above URL can be used as follows

String url="jdbc:databend://databend:secret@0.0.0.0:8000/hello_databend"
        Connection conn=DriverManager.getConnection(url);

If you are using Databend Cloud, you can get a warehouse DSN according to this doc. Then the above URL within warehouse DSN can be used as follows:

        String url="jdbc:databend://cloudapp:password@tnf34b0rm--elt-wh-medium.gw.aliyun-cn-beijing.default.databend.cn:443/db_name?ssl=true"
        Connection conn=DriverManager.getConnection(url);

Databend JDBC URLs accept a single host. Automatic node discovery, load balancing, and failover are not supported.

Arrow result format

By default, query results are returned in JSON format. To fetch query results in Arrow format, set query_result_format=arrow in the JDBC URL:

jdbc:databend://databend:secret@0.0.0.0:8000/hello_databend?query_result_format=arrow

Arrow mode is used for query result fetching. If query_result_format is not set, the driver uses JSON.

When Arrow is enabled, start the JVM with:

export JAVA_TOOL_OPTIONS='--add-opens=java.base/java.nio=ALL-UNNAMED -Dio.netty.tryReflectionSetAccessible=true'

Or pass the same options directly to java:

java --add-opens=java.base/java.nio=ALL-UNNAMED -Dio.netty.tryReflectionSetAccessible=true -jar your-app.jar

Connection parameters

The driver supports various parameters that may be set as URL parameters or as properties passed to DriverManager. Both of the following examples are equivalent:

// URL parameters
String url="jdbc:databend://databend:secret@0.0.0.0:8000/hello_databend";
        Properties properties=new Properties();
        properties.setProperty("user","test");
        properties.setProperty("password","secret");
        properties.setProperty("SSL","true");
        Connection connection=DriverManager.getConnection(url,properties);

// properties
        String url="jdbc:databend://databend:secret@0.0.0.0:8000/hello_databend?user=test&password=secret&SSL=true";
        Connection connection=DriverManager.getConnection(url);

Parameter References

Parameter Description Default example
user Databend user name none jdbc:databend://0.0.0.0:8000/hello_databend?user=test
password Databend user password none jdbc:databend://0.0.0.0:8000/hello_databend?password=secret
SSL Enable SSL false jdbc:databend://0.0.0.0:8000/hello_databend?SSL=true
sslmode SSL mode disable jdbc:databend://0.0.0.0:8000/hello_databend?sslmode=enable
copy_purge If True, the command will purge the files in the stage after they are loaded successfully into the table false jdbc:databend://0.0.0.0:8000/hello_databend?copy_purge=true
presigned_url_disabled whether use presigned url to upload data, generally if you use local disk as your storage layer, it should be set as true false jdbc:databend://0.0.0.0:8000/hello_databend?presigned_url_disabled=true
presign Controls presign mode for data upload. Values: auto (enable for *.databend.com, *.databend.cn, *.tidbcloud.com hosts, disable otherwise), detect (probe the server to determine support), on (always enable), off (always disable). When set, takes precedence over presigned_url_disabled none jdbc:databend://0.0.0.0:8000/hello_databend?presign=auto
query_result_format Query result format. Supported values: json and arrow. Default is json json jdbc:databend://0.0.0.0:8000/default?query_result_format=arrow
wait_time_secs Restful query api blocking time, if the query is not finished, the api will block for wait_time_secs seconds 10 jdbc:databend://0.0.0.0:8000/hello_databend?wait_time_secs=10
max_rows_per_page the maximum rows per page in response data body 100000 jdbc:databend://0.0.0.0:8000/default?max_rows_per_page=100000
null_display null value display \N jdbc:databend://0.0.0.0:8000/hello_databend?null_display=null
binary_format binary format, support hex and base64 hex jdbc:databend://0.0.0.0:8000/default?binary_format=hex
use_verify whether verify the server before establishing the connection true jdbc:databend://0.0.0.0:8000/default?use_verify=true
debug whether enable debug mode false jdbc:databend://0.0.0.0:8000/default?debug=true
session_settings set databend session settings "" jdbc:databend://0.0.0.0:8000/default?session_settings="key1=value1,key2=value2"