JDBC Driver for YDB

Quickstart

1. Drop in JDBC driver to classpath or pick this file in IDE
2. Connect to YDB
   • Local or remote Docker (anonymous authentication):
     jdbc:ydb:grpc://localhost:2136/local
   • Self-hosted cluster:
     jdbc:ydb:grpcs://<host>:2135/Root/testdb?secureConnectionCertificate=~/myca.cer
   • Connect with token to the cloud instance:
     jdbc:ydb:grpcs://<host>:2135/path/to/database?tokenFile=~/my_token
   • Connect with service account to the cloud instance:
     jdbc:ydb:grpcs://<host>:2135/path/to/database?saKeyFile=~/sa_key.json
3. Execute queries, see example in YdbDriverExampleTest.java

Usage with Maven

The recommended way to use the YDB JDBC driver in your project is to consume it from Maven. Specify the YDB JDBC driver in the dependencies:

<dependencies>
    <!-- Base version -->
    <dependency>
        <groupId>tech.ydb.jdbc</groupId>
        <artifactId>ydb-jdbc-driver</artifactId>
        <version>2.3.5</version>
    </dependency>

    <!-- Shaded version with included dependencies -->
    <dependency>
        <groupId>tech.ydb.jdbc</groupId>
        <artifactId>ydb-jdbc-driver-shaded</artifactId>
        <version>2.3.5</version>
    </dependency>
</dependencies>

Authentication modes

YDB JDBC Driver supports the following authentication modes:

• Anonymous: no authentication, used when username and password are not specified and no other authentication properties configured;
• Static Credentials: used when username and password are specified;
• Access Token: used when token property is configured, needs YDB authentication token as printed by the ydb auth get-token CLI command;
• Metadata: used when useMetadata property is set to true, extracts the authentication data from the metadata of a virtual machine, serverless container or a serverless function running in a cloud environment;
• Service Account Key: used when saFile property is configured, extracts the service account key and uses it for authentication.

Driver properties reference

Driver supports the following configuration properties, which can be specified in the URL or passed via extra properties:

• saKeyFile - file location of service account key for authentication;
• tokenFile - file location with token value for token based authentication;
• iamEndpoint - custom IAM endpoint for authentication via service account key;
• useMetadata - boolean value, true if metadata authentication should be used, false otherwise (and default);
• metadataURL - custom metadata endpoint;
• localDatacenter - name of the datacenter local to the application being connected;
• secureConnection - boolean value, true if TLS should be enforced (normally configured via grpc:// or grpcs:// scheme in the JDBC URL);
• secureConnectionCertificate - custom CA certificate for TLS connections, can be passed either as literal value or as a file reference.

Using TableService mode

By default JDBC driver executes all queries via QueryService, which uses grpc streams for the results recieving. If your database instance doesn't support this service, you can use old TableService mode by passing property useQueryService=false to the JDBC URL.

Building

By default all tests are run using a local YDB instance in Docker (if host has Docker or Docker Machine installed) To disable these tests run mvn test -DYDB_DISABLE_INTEGRATION_TESTS=true