Skip to content

Commit

Permalink
feat: YDB JOOQ extension doc (#8933)
Browse files Browse the repository at this point in the history 
Co-authored-by: Ivan Blinkov <ivan@ydb.tech>
  • Loading branch information
@KirillKurdyukov @blinkov
KirillKurdyukov and blinkov authored Sep 20, 2024
1 parent 41236b0 commit 873eaad
Show file tree
Hide file tree
Showing 6 changed files with 419 additions and 9 deletions.
7 changes: 4 additions & 3 deletions ydb/docs/en/core/integrations/orm/_includes/toc-table.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Object–relational mapping (ORM)

| Delivery System | Instruction |
| --- | --- |
| [Hibernate](https://hibernate.org/orm/) | [Instruction](../hibernate.md) |
| Delivery System | Instruction |
|-----------------------------------------------------------------|---------------------------------------|
| [Hibernate](https://hibernate.org/orm/) | [Instruction](../hibernate.md) |
| [Spring Data JDBC](https://spring.io/projects/spring-data-jdbc) | [Instruction](../spring-data-jdbc.md) |
| [JOOQ](https://www.jooq.org/) | [Instruction](../jooq.md) |

202 changes: 202 additions & 0 deletions ydb/docs/en/core/integrations/orm/jooq.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
# JOOQ extension for {{ ydb-short-name }}

This guide explains how to use [JOOQ](https://www.jooq.org/) with {{ ydb-short-name }}.

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 {#generated-java-classes}

You can generate Java classes using any of the tools provided on the [official JOOQ website](https://www.jooq.org/doc/latest/manual/code-generation/codegen-configuration/). Two dependencies are required: the [{{ ydb-short-name }} JDBC driver](https://github.com/ydb-platform/ydb-jdbc-driver) and the JOOQ extension for {{ ydb-short-name }}, 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:

```xml
<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](../../dev/yql-tutorial/create_demo_tables.md) (full file contents are [available on GitHub](https://github.com/ydb-platform/ydb-java-examples/tree/master/jdbc/spring-jooq/src/main/java/ydb/default_schema)):

```text
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 {#usage}

To integrate {{ ydb-short-name }} with JOOQ into your project, you need to add two dependencies: {{ ydb-short-name }} JDBC Driver and the JOOQ extension for {{ ydb-short-name }}.

Examples for different build systems:

{% list tabs %}

- Maven

```xml
<!-- 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>
```

- Gradle

```groovy
dependencies {
// Set actual versions
implementation "tech.ydb.dialects:jooq-ydb-dialect:$jooqYdbDialectVersion"
implementation "tech.ydb.jdbc:ydb-jdbc-driver:$ydbJdbcVersion"
}
```

{% endlist %}

To obtain a `YdbDSLContext` class instance (an extension of `org.jooq.DSLContext`), use the `tech.ydb.jooq.YDB` class. For example:

```java
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

```java
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`:

- [`UPSERT`](../../yql/reference/syntax/upsert_into.md):

```java
// 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();
}
```

- [`REPLACE`](../../yql/reference/syntax/replace_into.md):

```java
// 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`:

```java
// 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-short-name }} dialect follows the [JOOQ documentation](https://www.jooq.org/doc/latest/manual/).

### Spring Boot Configuration

Extend `JooqAutoConfiguration.DslContextConfiguration` with your own `YdbDSLContext`. For example:

```java
@Configuration
public class YdbJooqConfiguration extends JooqAutoConfiguration.DslContextConfiguration {

@Override
public YdbDSLContextImpl dslContext(org.jooq.Configuration configuration) {
return YdbDSLContextImpl(configuration);
}
}
```

```properties
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](https://github.com/ydb-platform/ydb-java-examples/tree/master/jdbc/spring-jooq).
4 changes: 3 additions & 1 deletion ydb/docs/en/core/integrations/orm/toc-orm.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,6 @@ items:
- name: Spring Data JDBC
href: spring-data-jdbc.md
- name: Hibernate
href: hibernate.md
href: hibernate.md
- name: JOOQ
href: jooq.md
9 changes: 5 additions & 4 deletions ydb/docs/ru/core/integrations/orm/_includes/toc-table.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Объектно-реляционное отображение (ORM)

| Система | Инструкция |
| --- | --- |
| [Hibernate](https://hibernate.org/orm/) | [Инструкция](../hibernate.md) |
| [Spring Data JDBC](https://spring.io/projects/spring-data-jdbc) | [Инструкция](../spring-data-jdbc.md) |
| Система | Инструкция |
|-----------------------------------------------------------------|--------------------------------------|
| [Hibernate](https://hibernate.org/orm/) | [Инструкция](../hibernate.md) |
| [Spring Data JDBC](https://spring.io/projects/spring-data-jdbc) | [Инструкция](../spring-data-jdbc.md) |
| [JOOQ](https://www.jooq.org/) | [Инструкция](../jooq.md) |
Loading

0 comments on commit 873eaad

Please sign in to comment.