From 46c0a3760fa39f78176d8576cddcc44cbaadece3 Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Fri, 17 Jan 2025 08:44:31 +0100 Subject: [PATCH] [jOOQ/jOOQ#16409] Improve Javadoc and log DEBUG message on RETURNING clauses, stressing that they can't return any rows for tables without identity in some dialects --- .../java/org/jooq/DeleteReturningStep.java | 24 +++++++-- .../java/org/jooq/InsertReturningStep.java | 50 ++++++++++++------- .../java/org/jooq/UpdateReturningStep.java | 24 +++++++-- .../java/org/jooq/impl/AbstractDMLQuery.java | 9 ++++ 4 files changed, 79 insertions(+), 28 deletions(-) diff --git a/jOOQ/src/main/java/org/jooq/DeleteReturningStep.java b/jOOQ/src/main/java/org/jooq/DeleteReturningStep.java index 4b0e4b54d4..2ab2255bc1 100644 --- a/jOOQ/src/main/java/org/jooq/DeleteReturningStep.java +++ b/jOOQ/src/main/java/org/jooq/DeleteReturningStep.java @@ -56,20 +56,34 @@ import org.jetbrains.annotations.NotNull; /** * This type is used for the {@link Delete}'s DSL API. *

- * Example: 


+ * Example:
+ *
+ * 
+ * 
  * DSLContext create = DSL.using(configuration);
  *
  * create.delete(table)
  *       .where(field1.greaterThan(100))
  *       .execute();
- * 

+ * 
+ *
*

* This implemented differently for every dialect: *

*

*

Referencing XYZ*Step types directly from client code

diff --git a/jOOQ/src/main/java/org/jooq/InsertReturningStep.java b/jOOQ/src/main/java/org/jooq/InsertReturningStep.java index 476900315e..0933782ca8 100644 --- a/jOOQ/src/main/java/org/jooq/InsertReturningStep.java +++ b/jOOQ/src/main/java/org/jooq/InsertReturningStep.java @@ -39,13 +39,16 @@ package org.jooq; import org.jetbrains.annotations.*; - +import java.sql.Statement; import java.util.Collection; /** * This type is used for the {@link Insert}'s DSL API. *

- * Example: 


+ * Example:
+ *
+ * 
+ * 
  * DSLContext create = DSL.using(configuration);
  *
  * TableRecord<?> record =
@@ -53,27 +56,38 @@ import java.util.Collection;
  *       .values(value1, value2)
  *       .returning(field1)
  *       .fetchOne();
- * 

+ * 
+ *
*

* This implemented differently for every dialect: *

*

+ * Note that if jOOQ cannot fetch any identity value in your given + * dialect because 1) there is no native SQL syntax or 2) there is no identity + * column, or 3) there is no support for fetching any identity values, then the + * INSERT … RETURNING statement will simply not produce any + * rows! + *

*

Referencing XYZ*Step types directly from client code

*

* It is usually not recommended to reference any XYZ*Step types diff --git a/jOOQ/src/main/java/org/jooq/UpdateReturningStep.java b/jOOQ/src/main/java/org/jooq/UpdateReturningStep.java index 982047ffaf..97558af07f 100644 --- a/jOOQ/src/main/java/org/jooq/UpdateReturningStep.java +++ b/jOOQ/src/main/java/org/jooq/UpdateReturningStep.java @@ -56,7 +56,10 @@ import org.jetbrains.annotations.NotNull; /** * This type is used for the {@link Update}'s DSL API. *

- * Example: 


+ * Example:
+ *
+ * 
+ * 
  * DSLContext create = DSL.using(configuration);
  *
  * TableRecord<?> record =
@@ -65,14 +68,25 @@ import org.jetbrains.annotations.NotNull;
  *       .set(field2, value2)
  *       .returning(field1)
  *       .fetchOne();
- * 

+ * 
+ *
*

* This implemented differently for every dialect: *

*

*

Referencing XYZ*Step types directly from client code

diff --git a/jOOQ/src/main/java/org/jooq/impl/AbstractDMLQuery.java b/jOOQ/src/main/java/org/jooq/impl/AbstractDMLQuery.java index bddc5e6ce0..dbdac1ee57 100644 --- a/jOOQ/src/main/java/org/jooq/impl/AbstractDMLQuery.java +++ b/jOOQ/src/main/java/org/jooq/impl/AbstractDMLQuery.java @@ -1113,6 +1113,7 @@ abstract class AbstractDMLQuery extends AbstractRowCountQuery } // Column stores don't seem support fetching generated keys else if (NO_SUPPORT_FETCHING_KEYS.contains(ctx.dialect())) { + log.debug("RETURNING was set on query, but dialect doesn't support fetching generated keys: " + ctx.dialect()); return super.execute(ctx, listener); } else { @@ -1135,6 +1136,7 @@ abstract class AbstractDMLQuery extends AbstractRowCountQuery .fetch(); returnedResult.attach(((DefaultExecuteContext) ctx).originalConfiguration()); + logOnEmptyReturned(ctx); return result; } else @@ -1344,6 +1346,11 @@ abstract class AbstractDMLQuery extends AbstractRowCountQuery } } + private final void logOnEmptyReturned(Scope ctx) { + if (estimatedRowCount(ctx) == 1) + log.debug("RETURNING was set on query, but no rows were returned. This is likely due to a missing identity column (or an identity column unknown to jOOQ)."); + } + private final int executeReturningGeneratedKeys(ExecuteContext ctx, ExecuteListener listener) throws SQLException { listener.executeStart(ctx); int result = executeImmediate(ctx.statement()).executeUpdate(); @@ -1459,6 +1466,8 @@ abstract class AbstractDMLQuery extends AbstractRowCountQuery } } } + else + logOnEmptyReturned(derivedConfiguration.dsl()); } private final Field returnedIdentity() {