Use the jOOQ-Refaster Module for Automatic Migration off of Deprecated jOOQ API

Deprecation notice

After encountering numerous problems building the jOOQ-refaster module in various JDK versions and after receiving no feedback from the community about this feature, we have decided to remove it again in jOOQ 3.15:

Starting with jOOQ 3.13, we’re offering a new module called jOOQ Refaster, which provides refaster templates for automatic API migration.

What’s Refaster?

Refaster is a lesser known sub project of the popular Google Error Prone library, a library for static code analysis, implemented as a Java compiler plugin. We already support a few such static code analysis tools through the jOOQ Checker module, which can be used with both the Checker Framework and with Google’s Error Prone.

Refaster allows for finding “bad” API usage patterns in your code, and produce .patch files automatically, which fix such patterns, producing better code.

What are we offering in jOOQ?

Over the years, we have deprecated quite a bit of API, as new API came along. For example, there is the ResultQuery.fetchLazy(int) method, where the int parameter corresponds to the JDBC fetchSize that is being passed along to JDBC.

Long ago, we introduced better API for passing the fetchSize. You can:

  • Specify a Settings value with your configuration for a global fetchSize to apply
  • Specify ResultQuery.fetchSize(int), which can then be combined with fetchLazy(), or with any type of fetch() call, as this isn’t really specific to “lazy” fetching

The Javadoc says:

Deprecated. [#2811] – 3.3.0 – Use fetchSize(int) and fetchLazy() instead.

…and your IDE will probably warn you about deprecated API usage, but who has time to fix all these warnings and read all these Javadoc?

Instead, you can now download the refaster file for your jOOQ version from our website, configure your Java compiler to include ErrorProne’s refaster library (as documented in the jOOQ manual), and get a patch right away.

For example, if your code reads:

public void runQuery() {
    try (Cursor<?> cursor =
       .fetchLazy(42)) {
        // Do something

You might be getting a patch file like this one:

--- ..\..\src\main\java\org\jooq\refaster\test\
+++ ..\..\src\main\java\org\jooq\refaster\test\
@@ -62,6 +62,5 @@
 public void runQuery() {
     try (Cursor<?> cursor =
-       .from(T)
-       .fetchLazy(42)) {
+       .from(T).fetchSize(42).fetchLazy()) {
         // Do something

And you’ll get the improved version of your code automatically:

public void runQuery() {
    try (Cursor<?> cursor =
       .from(T).fetchSize(42).fetchLazy()) {
        // Do something

In our opinion, all libraries should offer such refaster files (or another technology doing something similar) to help users upgrade more easily between versions.

What’s next?

In addition to upgrading deprecated API usage (which is a very obvious use-case for Refaster), we’re also experimenting with some other static code analysis and improvement approaches that deal with our understanding of the SQL language, and best practices. For example, as we’ve blogged before, it is not recommended to use COUNT(*) queries in SQL (or in any language), when a simple EXISTS() check would suffice.

jOOQ 3.13 already offers an introspection that replaces calls like these:

ctx.fetchCount(table) != 0
ctx.fetchCount(table) >= 1 // And many more

By equivalent, but likely much more performant expressions:


So, stay tuned for more such goodies in the future!

Alvor: Static SQL analysis in Strings passed to JDBC

I have recently discovered this nice Eclipse plugin here:

It evaluates String, StringBuilder, StringBuffer, CharSequence and many other types passed to JDBC method for subsequent execution. It doesn’t do a bad job at this, even if it is in beta mode. The rate of false positives that I have experienced is around 20% for regular SQL statements, and 100% for stored procedure calls (which seem not to be supported). Checks include:

  • Syntax correctness
  • Semantics correctness
  • Object availability

It does so by

  • Comparing SQL against its own internal SQL grammar
  • Checking SQL statements against an actual database (provided a JDBC driver, JDBC URL, user, password)

This is extremely powerful, as it can find common bugs resulting from bad SQL string concatenation, misspelled table / column names, type mismatches, etc. With findbugs’ capabilities of analysing control flows, this could be made even better to detect even remote corner-cases or SQL passed to methods for the concatenation of sub-clauses and sub-selects. An example screenshot is given on their website:

An Alvor Screenshot


Check out Alvor for yourself here:

Note, I have also posted a request to the FindBugs mailing list here:

Static SQL analysis of this sort would be a great addition to FindBugs. If you think so, too, please support my request on the FindBugs mailing list