Java/jOOQ: Add code generation add-on for Gradle, with reflection from SQL DDL files

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,24 +35,48 @@ In some kind, jOOQ is similar to `LINQ`_, `but better <Insight into Language
 Integrated Querying_>`_.
 
 
+*******
 Details
-=======
+*******
+
+Overview
+========
+
+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`_.
 
-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`_.
+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`_ takes your database schema and reverse-engineers it
-  into a set of Java classes. This feature currently does not work with CrateDB
-  yet. The code provided within the ``src/generated`` directory has not been
-  derived by reflecting the database schema from CrateDB.
+- `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,16 +97,26 @@ Usage
 
     ./gradlew test
 
+4. Generate the jOOQ sources from the main jOOQ configuration, see ``jooq.gradle``::
+
+    ./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'
@@ -56,6 +57,9 @@ test {
     dependsOn 'cleanTest'
 }
 
+// Activate jOOQ code generation add-on.
+apply from: 'jooq.gradle'
+
 idea.module.inheritOutputDirs = true
 processResources.destinationDir = compileJava.destinationDir
 compileJava.dependsOn processResources

by-language/java-jooq/jooq.gradle

@@ -0,0 +1,119 @@
+/**
+ * About
+ * =====
+ *
+ * Configure `gradle-jooq-plugin`, a Gradle plugin that integrates the jOOQ
+ * code generation tool. This layout manages the jOOQ configuration within
+ * a separate script file.
+ *
+ * Synopsis
+ * ========
+ *
+ *     ./gradlew generateJooq
+ *
+ * Resources
+ * =========
+ *
+ * - https://github.com/etiennestuder/gradle-jooq-plugin#gradle-groovy-dsl-4
+ * - https://github.com/etiennestuder/gradle-jooq-plugin/tree/main/example/extract_script_file
+ * - https://github.com/etiennestuder/gradle-jooq-plugin#examples
+ */
+
+buildscript {
+    repositories {
+        gradlePluginPortal()
+    }
+    dependencies {
+        classpath 'nu.studer:gradle-jooq-plugin:8.1'
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+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 {
+
+    configurations {
+        // Name of the jOOQ configuration.
+        main {
+
+            // Do not *automatically* generate code.
+            generateSchemaSourceOnCompilation = false
+
+            generationTool {
+                logging = org.jooq.meta.jaxb.Logging.WARN
+                generator {
+                    name = 'org.jooq.codegen.DefaultGenerator'
+                    strategy.name = 'org.jooq.codegen.DefaultGeneratorStrategy'
+                    database {
+                        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 = true
+                        immutablePojos = false
+                        fluentSetters = false
+                    }
+                    target {
+                        packageName = 'io.crate.demo.jooq.model'
+                        directory = 'src/generated/java'
+                    }
+                }
+            }
+        }
+    }
+}