Skip to content

Java/jOOQ: Improve documentation #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 6, 2023
Merged

Java/jOOQ: Improve documentation #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7bc1ed6
Java/jOOQ: Improve README
amotl Jan 25, 2023
b00688f
Java/jOOQ: Add curated backlog from development notes
amotl Jan 25, 2023
bfadfdc
Java/jOOQ: A few more documentation edits
amotl Jan 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 35 additions & 22 deletions by-language/java-jooq/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,28 @@
.. highlight:: sh

############################################################
Java jOOQ demo application for CrateDB using PostgreSQL JDBC
############################################################
#############################################################
Java jOOQ demo application with CrateDB using PostgreSQL JDBC
#############################################################


*****
About
*****

A demo application using `CrateDB`_ with `jOOQ`_ and the `PostgreSQL
JDBC driver`_.
A demo application using `CrateDB`_ with `jOOQ`_ and the `PostgreSQL JDBC
driver`_. It uses the `Gradle Build Tool`_ and the `Gradle plugin for jOOQ code
generation`_.

It is intended as a basic example to demonstrate what currently works, and as a
testing rig for eventually growing a full-fledged CrateDB dialect.
testing rig for eventually growing a full-fledged CrateDB extension.
Contributions are welcome.

Introduction
============

The idea of jOOQ is to generate typesafe code based on the SQL schema.
********
Synopsis
********

The idea of jOOQ is to generate typesafe code based on an SQL schema.
Then, accessing a database table using the jOOQ DSL API looks like this:

.. code-block:: java
Expand All @@ -31,8 +34,12 @@ Then, accessing a database table using the jOOQ DSL API looks like this:
.orderBy(AUTHOR.NAME)
.fetch();

In some kind, jOOQ is similar to `LINQ`_, `but better <Insight into Language
Integrated Querying_>`_.
// Iterate and display records.
for (Record record : result) {
Integer id = record.getValue(AUTHOR.ID);
String name = record.getValue(AUTHOR.NAME);
System.out.println("id: " + id + ", name: " + name);
}


*******
Expand Down Expand Up @@ -63,21 +70,27 @@ directory has been generated like this.
Caveats
=======

Contributions to resolve any of those items will be welcome, see also
`backlog`_.

- `jOOQ's code generator`_ currently does not work with directly connecting to
a real CrateDB database instance and reflecting the schema from there.
Because SQL DDL statements are usually maintained in form of multiple
incremental migration scripts anyway, this is considered to be not of a too
big concern, see above. With corresponding improvements to CrateDB, this
can be made work in the future, see `issue #10 - with reflection from the
database`_.
With corresponding improvements to CrateDB, this can be made work in the
future, see `issue #10 - with reflection from the database`_. Right now, this
example uses code generation based on SQL DDL files, which is also supported
by jOOQ.

- Applying code generation based on the database schema (directly, or via SQL
DDL) is only supported for schema definitions which use field types
compatible with standard PostgreSQL, and understood by jOOQ. jOOQ does not
know anything about any other special data types supported by CrateDB, and
does not support it. When using special field types, like ``OBJECT``,
``ARRAY``, or ``IP``, it will trip the code generator.

- Most of the jOOQ examples use uppercase letters for the database, table, and
field names. Within this setup, we have only been able to make it work using
lowercase letters.

- We have not been able to make multiple SQL DDL statements work within a
single SQL bootstrap file at ``src/main/resources/bootstrap.sql``.


*****
Usage
Expand All @@ -102,21 +115,21 @@ Usage
./gradlew generateJooq


.. _backlog: backlog.rst
.. _Bytebase: https://github.com/bytebase/bytebase
.. _CrateDB: https://github.com/crate/crate
.. _database schema migration: https://en.wikipedia.org/wiki/Schema_migration
.. _DDLDatabase - Code generation from SQL files: https://www.jooq.org/doc/latest/manual/code-generation/codegen-ddl/
.. _Different use cases for jOOQ: https://www.jooq.org/doc/latest/manual/getting-started/use-cases/
.. _Dynamic SQL API: https://www.jooq.org/doc/latest/manual/sql-building/dynamic-sql/
.. _Flyway: https://github.com/flyway/flyway
.. _Gradle: https://gradle.org/
.. _Insight into Language Integrated Querying: https://blog.jooq.org/jooq-tuesdays-ming-yee-iu-gives-insight-into-language-integrated-querying/
.. _Gradle Build Tool: https://gradle.org/
.. _Gradle plugin for jOOQ code generation: https://github.com/etiennestuder/gradle-jooq-plugin
.. _issue #10 - with reflection from the database: https://github.com/crate/cratedb-examples/pull/10
.. _Java 17: https://adoptium.net/temurin/releases/?version=17
.. _jOOQ: https://github.com/jOOQ/jOOQ
.. _jOOQ as a SQL builder without code generation: https://www.jooq.org/doc/latest/manual/getting-started/use-cases/jooq-as-a-sql-builder-without-codegeneration/
.. _jOOQ's code generator: https://www.jooq.org/doc/latest/manual/code-generation/
.. _jOOQ DSL API: https://www.jooq.org/doc/latest/manual/sql-building/dsl-api/
.. _LINQ: https://en.wikipedia.org/wiki/Language_Integrated_Query
.. _Liquibase: https://github.com/liquibase/liquibase
.. _PostgreSQL JDBC Driver: https://github.com/pgjdbc/pgjdbc
84 changes: 84 additions & 0 deletions by-language/java-jooq/backlog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
###################################################
Backlog for Java jOOQ demo application with CrateDB
###################################################


Features
========

- Evaluate more features of jOOQ, like:

- `Using JDBC batch operations`_
- `jOOQ for PROs`_, specifically but not exclusively `exporting`_ and `importing`_
- `Alternative execution models`_
- `The static query DSL API`_
- `Configuration and setup of the generator`_

- jOOQ's code generator does not know about CrateDB's special data types.
Evaluate if this will work when using the dynamic access variant, without
using code generation. Of course, the container data types ``OBJECT`` and
``ARRAY`` are the most interesting ones.


Q & A
=====

- Question: Out of curiosity, validate if, under the hood, the actual
abstraction layer is indeed ``org.hibernate.dialect.PostgreSQL94Dialect``?
Answer: Yes, as of jOOQ 3.17.7, this is correct, see
`org.jooq.SQLDialect#L1367-L1368`_.

- Question: How to set the default schema name? The ``unqualifiedSchema``
property in ``jooq.gradle`` apparently only accepts ``public`` or ``none``.
Answer: Please check the other ``jooq.gradle`` in branch
``amo/jooq/codegen``, see `jooq.gradle#L70-L73`_::

database {
name = 'org.jooq.meta.postgres.PostgresDatabase'
inputSchema = 'testdrive'
}


Other topics
============

- When jOOQ connects to CrateDB, it displays ``SET SESSION STATEMENT WILL BE
IGNORED: extra_float_digits`` on the server console.
Comment on lines +45 to +46
Copy link
Member Author

@amotl amotl Jan 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think this observation should be carried over to the CrateDB repository by creating an issue?


- Demonstrate usage together with `HikariCP`_, a high-performance JDBC
connection pool.

- Discussion: Would it be sensible to get CrateDB into the `List of RDBMS
supported by jOOQ`_, and what would it take?


Caveats
=======

The `README`_ lists multiple items in the "Caveats" section. Address them, when
possible.

- `Code generation with reflection from the database`_ has been evaluated, but
does not work yet. The corresponding blockers are, at least, `support for
"WITH RECURSIVE" CTEs`_, and `IllegalStateException on nested JOINs`_.
The first ones happens when jOOQ issues a reflection query using the
``org.jooq.meta.postgres.PostgresDatabase`` code generator, and the second
one happens when using the ``org.jooq.meta.jdbc.JDBCDatabase`` generator.



.. _Alternative execution models: https://www.jooq.org/doc/latest/manual/sql-execution/alternative-execution-models/
.. _code generation with reflection from the database: https://github.com/crate/cratedb-examples/pull/10
.. _Configuration and setup of the generator: https://www.jooq.org/doc/latest/manual/code-generation/codegen-configuration/
.. _exporting: https://www.jooq.org/doc/latest/manual/sql-execution/exporting/
.. _HikariCP: https://github.com/brettwooldridge/HikariCP
.. _IllegalStateException on nested JOINs: https://github.com/crate/crate/issues/13503
.. _importing: https://www.jooq.org/doc/latest/manual/sql-execution/importing/
.. _jOOQ for PROs: https://www.jooq.org/doc/latest/manual/getting-started/use-cases/jooq-for-pros/
.. _jooq.gradle#L70-L73: https://github.com/crate/cratedb-examples/blob/f88eda5/by-language/java-jooq/jooq.gradle#L70-L73
.. _List of RDBMS supported by jOOQ: https://www.jooq.org/doc/latest/manual/reference/supported-rdbms/
.. _org.jooq.SQLDialect#L1367-L1368: https://github.com/jOOQ/jOOQ/blob/version-3.17.7/jOOQ/src/main/java/org/jooq/SQLDialect.java#L1367-L1368
.. _README: README.rst
.. _Support for "WITH RECURSIVE" CTEs: https://github.com/crate/crate/issues/12544
.. _The static query DSL API: https://www.jooq.org/doc/latest/manual/sql-building/dsl/
.. _Using JDBC batch operations: https://www.jooq.org/doc/latest/manual/sql-execution/batch-execution/