- Drop in JDBC driver to classpath or pick this file in IDE
- 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=file:~/myca.cer
- Connect with token to the cloud instance:
jdbc:ydb:grpcs://<host>:2135/path/to/database?token=file:~/my_token
- Connect with service account to the cloud instance:
jdbc:ydb:grpcs://<host>:2135/path/to/database?saFile=file:~/sa_key.json
- Local or remote Docker (anonymous authentication):
- Execute queries, see example in YdbDriverExampleTest.java
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.2.11</version>
</dependency>
<!-- Shaded version with included dependencies -->
<dependency>
<groupId>tech.ydb.jdbc</groupId>
<artifactId>ydb-jdbc-driver-shaded</artifactId>
<version>2.2.11</version>
</dependency>
</dependencies>
By default JDBC driver executes all queries via TableService, so it brings corresponding limitations.
To eliminate these limitations you can try a new experimentail QueryService mode by passing property useQueryService=true
to the JDBC URL
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 whentoken
property is configured, needs YDB authentication token as printed by theydb auth get-token
CLI command;Metadata
: used whenuseMetadata
property is set totrue
, 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 whensaFile
property is configured, extracts the service account key and uses it for authentication.
Driver supports the following configuration properties, which can be specified in the URL or passed via extra properties:
saFile
- service account key for authentication, can be passed either as literal JSON value or as a file reference;iamEndpoint
- custom IAM endpoint for authentication via service account key;token
- token value for authentication, can be passed either as literal value or as a file reference;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 viagrpc://
orgrpcs://
scheme in the JDBC URL);secureConnectionCertificate
- custom CA certificate for TLS connections, can be passed either as literal value or as a file reference.
File references for saFile
, token
or secureConnectionCertificate
must be prefixed with the file:
URL scheme, for example:
saFile=file:~/mysaley1.json
token=file:/opt/secret/token-file
secureConnectionCertificate=file:/etc/ssl/cacert.cer
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