From f3832c7262514e8ef0ccf07ce198b0fd88b1a6b0 Mon Sep 17 00:00:00 2001
From: Juergen Hoeller <juergen.hoeller@broadcom.com>
Date: Mon, 28 Jul 2025 22:06:38 +0200
Subject: [PATCH] Add note on SQL types with SqlBinaryValue/SqlCharacterValue

Closes gh-34786
---
 .../jdbc/core/support/SqlBinaryValue.java            | 12 +++++++++---
 .../jdbc/core/support/SqlCharacterValue.java         | 11 ++++++++---
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlBinaryValue.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlBinaryValue.java
index 46672b4b0a5..fd796de79ca 100644
--- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlBinaryValue.java
+++ b/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlBinaryValue.java
@@ -34,12 +34,18 @@ import org.springframework.lang.Nullable;
  *
  * <p>Designed for use with {@link org.springframework.jdbc.core.JdbcTemplate}
  * as well as {@link org.springframework.jdbc.core.simple.JdbcClient}, to be
- * passed in as a parameter value wrapping the target content value. Can be
- * combined with {@link org.springframework.jdbc.core.SqlParameterValue} for
- * specifying a SQL type, for example,
+ * passed in as a parameter value wrapping the target content value.
+ *
+ * <p>Can be combined with {@link org.springframework.jdbc.core.SqlParameterValue}
+ * for specifying a SQL type, for example,
  * {@code new SqlParameterValue(Types.BLOB, new SqlBinaryValue(myContent))}.
  * With most database drivers, the type hint is not actually necessary.
  *
+ * <p>Note: Only specify {@code Types.BLOB} in case of an actual BLOB, preferring
+ * {@code Types.LONGVARBINARY} otherwise. With PostgreSQL, {@code Types.ARRAY}
+ * has to be specified for BYTEA columns, rather than {@code Types.BLOB}. This
+ * is in contrast to {@link SqlLobValue} where byte array handling was lenient.
+ *
  * @author Juergen Hoeller
  * @since 6.1.4
  * @see SqlCharacterValue
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlCharacterValue.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlCharacterValue.java
index e5f3f42deeb..97b1587c558 100644
--- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlCharacterValue.java
+++ b/spring-jdbc/src/main/java/org/springframework/jdbc/core/support/SqlCharacterValue.java
@@ -33,12 +33,17 @@ import org.springframework.lang.Nullable;
  *
  * <p>Designed for use with {@link org.springframework.jdbc.core.JdbcTemplate}
  * as well as {@link org.springframework.jdbc.core.simple.JdbcClient}, to be
- * passed in as a parameter value wrapping the target content value. Can be
- * combined with {@link org.springframework.jdbc.core.SqlParameterValue} for
- * specifying a SQL type, for example,
+ * passed in as a parameter value wrapping the target content value.
+ *
+ * <p>Can be combined with {@link org.springframework.jdbc.core.SqlParameterValue}
+ * for specifying a SQL type, for example,
  * {@code new SqlParameterValue(Types.CLOB, new SqlCharacterValue(myContent))}.
  * With most database drivers, the type hint is not actually necessary.
  *
+ * <p>Note: Only specify {@code Types.CLOB} in case of an actual CLOB, preferring
+ * {@code Types.LONGVARCHAR} otherwise. This is in contrast to {@link SqlLobValue}
+ * where char sequence handling was lenient.
+ *
  * @author Juergen Hoeller
  * @since 6.1.4
  * @see SqlBinaryValue