JOOQ extension for YDB
This guide explains how to use JOOQ with YDB.
JOOQ is a Java library that allows you to create type-safe SQL queries by generating Java classes from a database schema and providing convenient query builders.
Generating Java Classes
You can generate Java classes using any of the tools provided on the official JOOQ website. Two dependencies are required: the YDB JDBC driver and the JOOQ extension for YDB, along with two parameters:
database.name
:tech.ydb.jooq.codegen.YdbDatabase
(mandatory setting)strategy.name
:tech.ydb.jooq.codegen.YdbGeneratorStrategy
(recommended setting)
An example using the maven
plugin:
<plugin>
<groupId>org.jooq</groupId>
<artifactId>jooq-codegen-maven</artifactId>
<version>3.19.11</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>tech.ydb.jdbc</groupId>
<artifactId>ydb-jdbc-driver</artifactId>
<version>${ydb.jdbc.version}</version>
</dependency>
<dependency>
<groupId>tech.ydb.dialects</groupId>
<artifactId>jooq-ydb-dialect</artifactId>
<version>${jooq.ydb.version}</version>
</dependency>
</dependencies>
<configuration>
<jdbc>
<driver>tech.ydb.jdbc.YdbDriver</driver>
<url>jdbc:ydb:grpc://localhost:2136/local</url>
</jdbc>
<generator>
<strategy>
<name>tech.ydb.jooq.codegen.YdbGeneratorStrategy</name>
</strategy>
<database>
<name>tech.ydb.jooq.codegen.YdbDatabase</name>
<!-- excluding system tables -->
<excludes>.sys.*</excludes>
</database>
<target>
<packageName>ydb</packageName>
<directory>./src/main/java</directory>
</target>
</generator>
</configuration>
</plugin>
Example of generated classes from YQL tutorial (full file contents are available on GitHub):
ydb/DefaultCatalog.java
ydb/default_schema
ydb/default_schema/tables
ydb/default_schema/tables/Seasons.java
ydb/default_schema/tables/records
ydb/default_schema/tables/records/SeriesRecord.java
ydb/default_schema/tables/records/EpisodesRecord.java
ydb/default_schema/tables/records/SeasonsRecord.java
ydb/default_schema/tables/Series.java
ydb/default_schema/tables/Episodes.java
ydb/default_schema/Indexes.java
ydb/default_schema/Keys.java
ydb/default_schema/Tables.java
ydb/default_schema/DefaultSchema.java
Usage
To integrate YDB with JOOQ into your project, you need to add two dependencies: YDB JDBC Driver and the JOOQ extension for YDB.
Examples for different build systems:
<!-- Set actual versions -->
<dependency>
<groupId>tech.ydb.jdbc</groupId>
<artifactId>ydb-jdbc-driver</artifactId>
<version>${ydb.jdbc.version}</version>
</dependency>
<dependency>
<groupId>tech.ydb.dialects</groupId>
<artifactId>jooq-ydb-dialect</artifactId>
<version>${jooq.ydb.dialect.version}</version>
</dependency>
dependencies {
// Set actual versions
implementation "tech.ydb.dialects:jooq-ydb-dialect:$jooqYdbDialectVersion"
implementation "tech.ydb.jdbc:ydb-jdbc-driver:$ydbJdbcVersion"
}
To obtain a YdbDSLContext
class instance (an extension of org.jooq.DSLContext
), use the tech.ydb.jooq.YDB
class. For example:
String url = "jdbc:ydb:<schema>://<host>:<port>/path/to/database[?saFile=file:~/sa_key.json]";
Connection conn = DriverManager.getConnection(url);
YdbDSLContext dsl = YDB.using(conn);
or
String url = "jdbc:ydb:<schema>://<host>:<port>/path/to/database[?saFile=file:~/sa_key.json]";
try(CloseableYdbDSLContext dsl = YDB.using(url)) {
// ...
}
YdbDSLContext
is ready to use.
YQL statements
The following statements are available from the YQL syntax in YdbDSLContext
:
// generated SQL:
// upsert into `episodes` (`series_id`, `season_id`, `episode_id`, `title`, `air_date`)
// values (?, ?, ?, ?, ?)
public void upsert(YdbDSLContext context) {
context.upsertInto(EPISODES)
.set(record)
.execute();
}
// generated SQL:
// replace into `episodes` (`series_id`, `season_id`, `episode_id`, `title`, `air_date`)
// values (?, ?, ?, ?, ?)
public void replace(YdbDSLContext context) {
ydbDSLContext.replaceInto(EPISODES)
.set(record)
.execute();
}
VIEW index_name
:
// generated SQL:
// select `series`.`series_id`, `series`.`title`, `series`.`series_info`, `series`.`release_date`
// from `series` view `title_name` where `series`.`title` = ?
var record = ydbDSLContext.selectFrom(SERIES.useIndex(Indexes.TITLE_NAME.name))
.where(SERIES.TITLE.eq(title))
.fetchOne();
In all other respects, the YDB dialect follows the JOOQ documentation.
Spring Boot Configuration
Extend JooqAutoConfiguration.DslContextConfiguration
with your own YdbDSLContext
. For example:
@Configuration
public class YdbJooqConfiguration extends JooqAutoConfiguration.DslContextConfiguration {
@Override
public YdbDSLContextImpl dslContext(org.jooq.Configuration configuration) {
return YdbDSLContextImpl(configuration);
}
}
spring.datasource.driver-class-name=tech.ydb.jdbc.YdbDriver
spring.datasource.url=jdbc:ydb:<schema>://<host>:<port>/path/to/database[?saFile=file:~/sa_key.json]
A complete example of a simple Spring Boot application can be found on GitHub.