Support "RETURNING INTO" clause for INSERT/UPDATE/DELETE in Oracle database

config/checkstyle/custom-suppressions.xml

@@ -6,5 +6,6 @@
 
 <suppressions>
     <suppress checks="FileLength" files=".*AbstractSqlLikeQueryBuilder.*" />
+    <suppress checks="FileLength" files="SqlQueryBuilder.java" />
     <suppress files="[\\/]generated-src[\\/]" checks="[a-zA-Z0-9]*"/>
 </suppressions>

data-jdbc/src/main/java/io/micronaut/data/jdbc/mapper/ColumnNameByIndexCallableResultReader.java

@@ -0,0 +1,167 @@
+/*
+ * Copyright 2017-2025 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.data.jdbc.mapper;
+
+import io.micronaut.core.annotation.Experimental;
+import io.micronaut.core.annotation.Internal;
+import io.micronaut.core.convert.ConversionService;
+import io.micronaut.data.exceptions.DataAccessException;
+import io.micronaut.data.model.DataType;
+import io.micronaut.data.runtime.mapper.ResultReader;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+import java.math.BigDecimal;
+import java.sql.CallableStatement;
+import java.sql.Time;
+import java.util.Date;
+import java.util.Map;
+
+/**
+ * A result reader that uses the column name to retrieve the column index and then delegates to
+ * {@link ColumnIndexCallableResultReader} to read the value.
+ *
+ * @author radovanradic
+ * @since 5.0
+ */
+@Internal
+@Experimental
+public final class ColumnNameByIndexCallableResultReader implements ResultReader<CallableStatement, String> {
+
+    private final ColumnIndexCallableResultReader delegate;
+    private final Map<String, Integer> columnIndexesByName;
+
+    /**
+     * Constructs a new instance of ColumnNameByIndexCallableResultReader.
+     *
+     * @param delegate             The delegate {@link ColumnIndexCallableResultReader} to use for reading values
+     * @param columnIndexesByName  The map of column indexes by names used as out parameters for the callable statement
+     */
+    public ColumnNameByIndexCallableResultReader(ColumnIndexCallableResultReader delegate, Map<String, Integer> columnIndexesByName) {
+        this.delegate = delegate;
+        this.columnIndexesByName = columnIndexesByName;
+    }
+
+    @Override
+    public ConversionService getConversionService() {
+        return delegate.getConversionService();
+    }
+
+    private Integer getIndex(String columnName) {
+        if (columnIndexesByName.containsKey(columnName)) {
+            return columnIndexesByName.get(columnName);
+        }
+        throw new DataAccessException("Column name not found: " + columnName);
+    }
+
+    @Nullable
+    @Override
+    public Object readDynamic(@NonNull CallableStatement cs, @NonNull String index, @NonNull DataType dataType) {
+        return delegate.readDynamic(cs, getIndex(index), dataType);
+    }
+
+    @Override
+    public boolean next(CallableStatement cs) {
+        return delegate.next(cs);
+    }
+
+    @Override
+    public <T> T convertRequired(@NonNull Object value, Class<T> type) {
+        return delegate.convertRequired(value, type);
+    }
+
+    @Override
+    @Nullable
+    public Date readTimestamp(CallableStatement cs, String index) {
+        return delegate.readTimestamp(cs, getIndex(index));
+    }
+
+    @Override
+    @Nullable
+    public Time readTime(CallableStatement cs, String index) {
+        return delegate.readTime(cs, getIndex(index));
+    }
+
+    @Override
+    public long readLong(CallableStatement cs, String name) {
+        return delegate.readLong(cs, getIndex(name));
+    }
+
+    @Override
+    public char readChar(CallableStatement cs, String name) {
+        return delegate.readChar(cs, getIndex(name));
+    }
+
+    @Override
+    @Nullable
+    public Date readDate(CallableStatement cs, String name) {
+        return delegate.readDate(cs, getIndex(name));
+    }
+
+    @Nullable
+    @Override
+    public String readString(CallableStatement cs, String name) {
+        return delegate.readString(cs, getIndex(name));
+    }
+
+    @Override
+    public int readInt(CallableStatement cs, String name) {
+        return delegate.readInt(cs, getIndex(name));
+    }
+
+    @Override
+    public boolean readBoolean(CallableStatement cs, String name) {
+        return delegate.readBoolean(cs, getIndex(name));
+    }
+
+    @Override
+    public float readFloat(CallableStatement cs, String name) {
+        return delegate.readFloat(cs, getIndex(name));
+    }
+
+    @Override
+    public byte readByte(CallableStatement cs, String name) {
+        return delegate.readByte(cs, getIndex(name));
+    }
+
+    @Override
+    public short readShort(CallableStatement cs, String name) {
+        return delegate.readShort(cs, getIndex(name));
+    }
+
+    @Override
+    public double readDouble(CallableStatement cs, String name) {
+        return delegate.readDouble(cs, getIndex(name));
+    }
+
+    @Override
+    @Nullable
+    public BigDecimal readBigDecimal(CallableStatement cs, String name) {
+        return delegate.readBigDecimal(cs, getIndex(name));
+    }
+
+    @Override
+    public byte[] readBytes(CallableStatement cs, String name) {
+        return delegate.readBytes(cs, getIndex(name));
+    }
+
+    @Override
+    @Nullable
+    public <T> T getRequiredValue(CallableStatement cs, String name, Class<T> type) throws DataAccessException {
+        return delegate.getRequiredValue(cs, getIndex(name), type);
+    }
+
+}

data-jdbc/src/main/java/io/micronaut/data/jdbc/operations/DefaultJdbcRepositoryOperations.java

@@ -21,6 +21,9 @@
 import io.micronaut.context.annotation.Parameter;
 import io.micronaut.core.annotation.AnnotationMetadata;
 import io.micronaut.core.annotation.Internal;
+import io.micronaut.data.jdbc.mapper.ColumnNameByIndexCallableResultReader;
+import io.micronaut.data.model.runtime.QueryOutParameterBinding;
+import io.micronaut.data.runtime.mapper.sql.SqlJsonColumnReader;
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 import io.micronaut.core.beans.BeanProperty;
@@ -119,6 +122,7 @@
 import java.util.Collection;
 import java.util.EnumMap;
 import java.util.Iterator;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.NoSuchElementException;
@@ -403,6 +407,35 @@
     }
 
     private <T, R> List<R> findAll(Connection connection, SqlPreparedQuery<T, R> preparedQuery, boolean applyPageable) {
+        if (preparedQuery.getDialect() == Dialect.ORACLE && (
+            preparedQuery.getOperationType() == StoredQuery.OperationType.INSERT_RETURNING ||
+            preparedQuery.getOperationType() == StoredQuery.OperationType.UPDATE_RETURNING ||
+            preparedQuery.getOperationType() == StoredQuery.OperationType.DELETE_RETURNING)) {
+            try (CallableStatement cs = connection.prepareCall(preparedQuery.getQuery())) {
+                preparedQuery.bindParameters(new JdbcParameterBinder(connection, cs, preparedQuery));
+                OutParameterContext outCtx = registerOracleReturningOutParameters(cs, preparedQuery);
+                int inCount = outCtx.inCount();
+                List<String> columnNames = outCtx.columnNames();
+                cs.execute();
+                boolean isEntityResult = preparedQuery.getResultDataType() == DataType.ENTITY;
+                if (isEntityResult) {
+                    SqlResultEntityTypeMapper mapper = getSqlResultEntityTypeMapper(preparedQuery.getPersistentEntity(), columnNames, inCount);
+                    return List.of((R) mapper.readEntity(cs));
+                }
+                // Otherwise single field
+                List<R> result = new ArrayList<>();
+                result.add(
+                    (R) columnIndexCallableResultReader.readDynamic(
+                        cs,
+                        inCount + 1,
+                        preparedQuery.getResultDataType()
+                    )
+                );
+                return result;
+            } catch (SQLException e) {
+                throw new DataAccessException("Error executing Oracle SQL RETURNING: " + e.getMessage(), e);
+            }
+        }
         try (PreparedStatement ps = prepareStatement(connection::prepareStatement, preparedQuery, !applyPageable, false)) {
             preparedQuery.bindParameters(new JdbcParameterBinder(connection, ps, preparedQuery));
             return findAll(preparedQuery, ps);
@@ -411,6 +444,29 @@
         }
     }
 
+    /**
+     * Creates a {@link SqlResultEntityTypeMapper} instance to map the results from a {@link CallableStatement} to an entity.
+     * Currently used for INSERT/UPDATE/DELETE ... RETURNING for Oracle dialect.
+     *
+     * @param persistentEntity the persistent entity to be mapped
+     * @param columnNames      the column names of the result set
+     * @param inCount          the number of input parameters in the statement
+     * @return a {@link SqlResultEntityTypeMapper} instance
+     */
+    private SqlResultEntityTypeMapper getSqlResultEntityTypeMapper(RuntimePersistentEntity<?> persistentEntity, List<String> columnNames, int inCount) {
+        Map<String, Integer> columnIndexesByName = new LinkedHashMap<>(columnNames.size());
+        int pos = inCount;
+        for (String columnName : columnNames) {
+            columnIndexesByName.put(columnName, ++pos);
+        }
+        ColumnNameByIndexCallableResultReader resultReader = new ColumnNameByIndexCallableResultReader(columnIndexCallableResultReader,
+            columnIndexesByName);
+        SqlJsonColumnReader<CallableStatement> reader = jsonMapper != null ? () -> jsonMapper : null;
+        SqlResultEntityTypeMapper mapper = new SqlResultEntityTypeMapper<>(persistentEntity, resultReader,
+            Set.of(), reader, conversionService);
+        return mapper;
+    }
+
     private <T, R> List<R> findAll(SqlStoredQuery<T, R> sqlStoredQuery, PreparedStatement ps) throws SQLException {
         try (ResultSet rs = ps.executeQuery()) {
             return findAll(sqlStoredQuery, rs);
@@ -1114,11 +1170,30 @@
         return fallbackMapper.apply(sqlException);
     }
 
+    private OutParameterContext registerOracleReturningOutParameters(CallableStatement cs, SqlStoredQuery<?, ?> query) throws SQLException {
+        int inCount = query.getQueryBindings().size();
+        List<QueryOutParameterBinding> outParams = query.getOutParameterBindings();
+        if (CollectionUtils.isEmpty(outParams)) {
+            throw new DataAccessException("Missing OUT parameter metadata for Oracle RETURNING. SqlQueryBuilder must attach QueryOutParameterBinding list.");
+        }
+        int pos = inCount;
+        List<String> columnNames = new ArrayList<>(outParams.size());
+        for (QueryOutParameterBinding outParam : outParams) {
+            int sqlType = JdbcQueryStatement.findSqlType(outParam.dataType(), jdbcConfiguration.getDialect());
+            cs.registerOutParameter(++pos, sqlType);
+            columnNames.add(outParam.name());
+        }
+        return new OutParameterContext(inCount, columnNames);
+    }
+
     @Override
     public boolean isSupportsBatchInsert(JdbcOperationContext jdbcOperationContext, RuntimePersistentEntity<?> persistentEntity) {
         return isSupportsBatchInsert(persistentEntity, jdbcOperationContext.dialect);
     }
 
+    private record OutParameterContext(int inCount, List<String> columnNames) {
+    }
+
     private final class JdbcParameterBinder implements BindableParametersStoredQuery.Binder {
 
         private final SqlStoredQuery<?, ?> sqlStoredQuery;
@@ -1271,6 +1346,27 @@
         }
 
         private void executeReturning() {
+            // For Oracle, RETURNING is expressed via PL/SQL block with INTO placeholders.
+            // Use CallableStatement and OUT parameter to capture the generated id and out field parameters.
+            if (ctx.dialect == Dialect.ORACLE) {
+                try (CallableStatement cs = ctx.connection.prepareCall(storedQuery.getQuery())) {
+                    storedQuery.bindParameters(new JdbcParameterBinder(ctx.connection, cs, storedQuery),
+                        ctx.invocationContext, entity, previousValues);
+                    OutParameterContext outCtx = registerOracleReturningOutParameters(cs, storedQuery);
+                    int inCount = outCtx.inCount();
+                    List<String> columnNames = outCtx.columnNames();
+                    rowsUpdated = cs.executeUpdate();
+                    SqlResultEntityTypeMapper mapper = getSqlResultEntityTypeMapper(persistentEntity, columnNames, inCount);
+                    entity = (T) mapper.readEntity(cs);
+
+                    // Trigger post-load on the entity
+                    entity = DefaultJdbcRepositoryOperations.this.triggerPostLoad(entity, persistentEntity, ctx.annotationMetadata);
+                    return;
+                } catch (SQLException e) {
+                    throw new DataAccessException("Error executing Oracle SQL RETURNING: " + e.getMessage(), e);
+                }
+            }
+            // Default path (e.g. Postgres) uses PreparedStatement and maps a result set
             try (PreparedStatement ps = ctx.connection.prepareStatement(storedQuery.getQuery())) {
                 storedQuery.bindParameters(new JdbcParameterBinder(ctx.connection, ps, storedQuery), ctx.invocationContext, entity, previousValues);
                 List<T> result = (List<T>) findAll(storedQuery, ps);
@@ -1490,5 +1586,4 @@
 
     private record ConnectionContext(Connection connection, boolean needsToBeClosed) {
     }
-
 }