Java/jOOQ: Use code generation based on SQL DDL

This time, the code within the `src/generated` folder has truly been
generated using jOOQ 3.17.7.

- The code generator used for that is `DDLDatabase` [1].
- The relevant upstream documentation is [2].

[1] org.jooq.meta.extensions.ddl.DDLDatabase
[2] https://www.jooq.org/doc/latest/manual/code-generation/codegen-ddl/

Author: amotl

by-language/java-jooq/README.rst

@@ -4,6 +4,7 @@
 Java jOOQ demo application for CrateDB using PostgreSQL JDBC
 ############################################################
 
+
 *****
 About
 *****
@@ -12,9 +13,8 @@ A demo application using `CrateDB`_ with `jOOQ`_ and the `PostgreSQL
 JDBC driver`_.
 
 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, or at least
-making the code generator work. Contributions are welcome.
-
+testing rig for eventually growing a full-fledged CrateDB dialect.
+Contributions are welcome.
 
 Introduction
 ============
@@ -35,19 +35,48 @@ In some kind, jOOQ is similar to `LINQ`_, `but better <Insight into Language
 Integrated Querying_>`_.
 
 
+*******
 Details
-=======
+*******
+
+Overview
+========
 
-The code example will demonstrate a few of the `different use cases for jOOQ`_.
-That is, `Dynamic SQL`_, the `jOOQ DSL API`_, and how to use `jOOQ as a SQL
-builder without code generation`_.
+The code examples will demonstrate a few of the `different use cases for jOOQ`_.
+That is, how to use the `jOOQ DSL API`_ based on code generated with `jOOQ's
+code generator`_ to take your database schema and reverse-engineer it into a
+set of Java classes, as well how to use the `Dynamic SQL API`_ by using `jOOQ
+as a SQL builder without code generation`_.
 
+Schema management
+=================
+
+In many cases, the schema is defined in the form of SQL scripts, which can be
+used with a `database schema migration`_ framework like `Flyway`_,
+`Liquibase`_, `Bytebase`_, etc.
+
+The `DDLDatabase - Code generation from SQL files`_ feature can be used to
+effectively reflect the database schema from SQL DDL files, without needing
+a database instance at all. The code provided within the ``src/generated``
+directory has been generated like this.
 
 Caveats
 =======
 
+- `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`_.
+
 - Most of the jOOQ examples use uppercase letters for the database, table, and
-  field names. CrateDB currently only handles lowercase letters.
+  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``.
 
 
 *****
@@ -73,15 +102,21 @@ Usage
     ./gradlew generateJooq
 
 
+.. _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: https://www.jooq.org/doc/latest/manual/sql-building/dynamic-sql/
+.. _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/
+.. _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

by-language/java-jooq/build.gradle

@@ -22,6 +22,7 @@ repositories {
 
 dependencies {
     implementation 'org.jooq:jooq:3.17.7'
+    implementation 'org.jooq:jooq-meta:3.17.7'
     implementation 'org.postgresql:postgresql:42.5.1'
     implementation 'org.slf4j:slf4j-api:2.0.6'
     implementation 'org.slf4j:slf4j-simple:2.0.6'

by-language/java-jooq/jooq.gradle

@@ -36,14 +36,11 @@ apply plugin: nu.studer.gradle.jooq.JooqPlugin
 
 dependencies {
     jooqGenerator 'org.postgresql:postgresql:42.5.1'
+    jooqGenerator 'org.jooq:jooq-meta-extensions:3.17.7'
 }
 
 jooq {
 
-    // Defaults (can be omitted).
-    // version = '3.17.6'
-    // edition = nu.studer.gradle.jooq.JooqEdition.OSS
-
     configurations {
         // Name of the jOOQ configuration.
         main {
@@ -53,35 +50,68 @@ jooq {
 
             generationTool {
                 logging = org.jooq.meta.jaxb.Logging.WARN
-                jdbc {
-                    driver = 'org.postgresql.Driver'
-                    url = 'jdbc:postgresql://localhost:5432/testdrive'
-                    user = 'crate'
-                    password = ''
-                    properties {
-                        property {
-                            key = 'PAGE_SIZE'
-                            value = 2048
-                        }
-                    }
-                }
                 generator {
                     name = 'org.jooq.codegen.DefaultGenerator'
+                    strategy.name = 'org.jooq.codegen.DefaultGeneratorStrategy'
                     database {
-                        name = 'org.jooq.meta.postgres.PostgresDatabase'
-                        inputSchema = 'testdrive'
+                        name = 'org.jooq.meta.extensions.ddl.DDLDatabase'
+                        properties {
+
+                            // Specify the location of your SQL script.
+                            // You may use ant-style file matching, e.g. /path/**/to/*.sql
+                            //
+                            // Where:
+                            // - ** matches any directory subtree
+                            // - * matches any number of characters in a directory / file name
+                            // - ? matches a single character in a directory / file name
+                            property {
+                                key = 'scripts'
+                                value = 'src/main/resources/bootstrap.sql'
+                            }
+
+                            // The sort order of the scripts within a directory, where:
+                            //
+                            // - semantic: sorts versions, e.g. v-3.10.0 is after v-3.9.0 (default)
+                            // - alphanumeric: sorts strings, e.g. v-3.10.0 is before v-3.9.0
+                            // - flyway: sorts files the same way as flyway does
+                            // - none: doesn't sort directory contents after fetching them from the directory
+                            property {
+                                key = 'sort'
+                                value = 'semantic'
+                            }
+
+                            // The default schema for unqualified objects:
+                            //
+                            // - public: all unqualified objects are located in the PUBLIC (upper case) schema
+                            // - none: all unqualified objects are located in the default schema (default)
+                            //
+                            // This configuration can be overridden with the schema mapping feature
+                            property {
+                                key = 'unqualifiedSchema'
+                                value = 'none'
+                            }
+
+                            // The default name case for unquoted objects:
+                            //
+                            // - as_is: unquoted object names are kept unquoted
+                            // - upper: unquoted object names are turned into upper case (most databases)
+                            // - lower: unquoted object names are turned into lower case (e.g. PostgreSQL)
+                            property {
+                                key = 'defaultNameCase'
+                                value = 'lower'
+                            }
+                        }
                     }
                     generate {
                         deprecated = false
-                        records = false
+                        records = true
                         immutablePojos = false
                         fluentSetters = false
                     }
                     target {
                         packageName = 'io.crate.demo.jooq.model'
                         directory = 'src/generated/java'
                     }
-                    strategy.name = "org.jooq.codegen.DefaultGeneratorStrategy"
                 }
             }
         }