chore: support simple statement param metadata (#2163)

Add an option to use simple PreparedStatement ParameterMetadata that only uses client-side information. This prevents round-trips to Spanner when calling the method PreparedStatement#getParameterMetaData(), for example when these are triggered by frameworks like Spring Data.

This option is experimental and could be removed in future releases.

The option can be enabled by setting the system property `spanner.jdbc.use_simple_parameter_metadata=true`

Author: olavloite

src/main/java/com/google/cloud/spanner/jdbc/JdbcPreparedStatement.java

@@ -29,6 +29,7 @@
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableList;
 import com.google.rpc.Code;
+import java.sql.ParameterMetaData;
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.ResultSetMetaData;
@@ -117,8 +118,16 @@ public void addBatch() throws SQLException {
   }
 
   @Override
-  public JdbcParameterMetaData getParameterMetaData() throws SQLException {
+  public ParameterMetaData getParameterMetaData() throws SQLException {
     checkClosed();
+
+    // NOTE: JdbcSimpleParameterMetaData is an experimental feature that can be removed without
+    // warning in a future version. Your application should not assume that this feature will
+    // continue to be supported.
+    if (JdbcSimpleParameterMetaData.useSimpleParameterMetadata()) {
+      return new JdbcSimpleParameterMetaData(this.parameters);
+    }
+
     if (cachedParameterMetadata == null) {
       if (getConnection().getParser().isUpdateStatement(sql)
           && !getConnection().getParser().checkReturningClause(sql)) {

src/main/java/com/google/cloud/spanner/jdbc/JdbcSimpleParameterMetaData.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * 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
+ *
+ *       http://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 com.google.cloud.spanner.jdbc;
+
+import com.google.api.core.BetaApi;
+import com.google.cloud.spanner.connection.AbstractStatementParser.ParametersInfo;
+import java.sql.ParameterMetaData;
+import java.sql.SQLException;
+import java.sql.Types;
+
+/**
+ * {@link JdbcSimpleParameterMetaData} implements {@link ParameterMetaData} without a round-trip to
+ * Spanner. This is an experimental feature that can be removed in a future version without prior
+ * warning.
+ */
+@BetaApi
+class JdbcSimpleParameterMetaData implements ParameterMetaData {
+  static final String USE_SIMPLE_PARAMETER_METADATA_KEY =
+      "spanner.jdbc.use_simple_parameter_metadata";
+  private final ParametersInfo parametersInfo;
+
+  /**
+   * This is an experimental feature that can be removed in a future version without prior warning.
+   */
+  @BetaApi
+  static boolean useSimpleParameterMetadata() {
+    return Boolean.parseBoolean(System.getProperty(USE_SIMPLE_PARAMETER_METADATA_KEY, "false"));
+  }
+
+  JdbcSimpleParameterMetaData(ParametersInfo parametersInfo) {
+    this.parametersInfo = parametersInfo;
+  }
+
+  @Override
+  public int getParameterCount() throws SQLException {
+    return this.parametersInfo.numberOfParameters;
+  }
+
+  @Override
+  public int isNullable(int param) throws SQLException {
+    return ParameterMetaData.parameterNullableUnknown;
+  }
+
+  @Override
+  public boolean isSigned(int param) throws SQLException {
+    return false;
+  }
+
+  @Override
+  public int getPrecision(int param) throws SQLException {
+    return 0;
+  }
+
+  @Override
+  public int getScale(int param) throws SQLException {
+    return 0;
+  }
+
+  @Override
+  public int getParameterType(int param) throws SQLException {
+    return Types.OTHER;
+  }
+
+  @Override
+  public String getParameterTypeName(int param) throws SQLException {
+    return "unknown";
+  }
+
+  @Override
+  public String getParameterClassName(int param) throws SQLException {
+    return Object.class.getName();
+  }
+
+  @Override
+  public int getParameterMode(int param) throws SQLException {
+    return ParameterMetaData.parameterModeIn;
+  }
+
+  @Override
+  public <T> T unwrap(Class<T> iface) throws SQLException {
+    throw new SQLException("This is not a wrapper for " + iface.getName());
+  }
+
+  @Override
+  public boolean isWrapperFor(Class<?> iface) throws SQLException {
+    return false;
+  }
+}

src/test/java/com/google/cloud/spanner/jdbc/JdbcPreparedStatementTest.java

@@ -221,7 +221,7 @@ public void testParameters() throws SQLException, MalformedURLException {
       ps.setObject(52, "{}", JsonType.VENDOR_TYPE_NUMBER);
       ps.setObject(53, "{}", PgJsonbType.VENDOR_TYPE_NUMBER);
 
-      JdbcParameterMetaData pmd = ps.getParameterMetaData();
+      JdbcParameterMetaData pmd = (JdbcParameterMetaData) ps.getParameterMetaData();
       assertEquals(numberOfParams, pmd.getParameterCount());
       assertEquals(JdbcArray.class.getName(), pmd.getParameterClassName(1));
       assertEquals(ByteArrayInputStream.class.getName(), pmd.getParameterClassName(2));
@@ -281,7 +281,7 @@ public void testParameters() throws SQLException, MalformedURLException {
       assertEquals(String.class.getName(), pmd.getParameterClassName(51));
 
       ps.clearParameters();
-      pmd = ps.getParameterMetaData();
+      pmd = (JdbcParameterMetaData) ps.getParameterMetaData();
       assertEquals(numberOfParams, pmd.getParameterCount());
     }
   }
@@ -329,12 +329,12 @@ public void testSetNullValues() throws SQLException {
       ps.setNull(++index, Types.NULL);
       assertEquals(numberOfParameters, index);
 
-      JdbcParameterMetaData pmd = ps.getParameterMetaData();
+      JdbcParameterMetaData pmd = (JdbcParameterMetaData) ps.getParameterMetaData();
       assertEquals(numberOfParameters, pmd.getParameterCount());
       assertEquals(Timestamp.class.getName(), pmd.getParameterClassName(15));
 
       ps.clearParameters();
-      pmd = ps.getParameterMetaData();
+      pmd = (JdbcParameterMetaData) ps.getParameterMetaData();
       assertEquals(numberOfParameters, pmd.getParameterCount());
     }
   }

src/test/java/com/google/cloud/spanner/jdbc/PreparedStatementParameterMetadataTest.java

@@ -24,6 +24,7 @@
 import com.google.cloud.spanner.Statement;
 import com.google.cloud.spanner.connection.AbstractMockServerTest;
 import com.google.cloud.spanner.connection.SpannerPool;
+import com.google.spanner.v1.ExecuteSqlRequest;
 import com.google.spanner.v1.ResultSet;
 import com.google.spanner.v1.ResultSetMetadata;
 import com.google.spanner.v1.ResultSetStats;
@@ -133,6 +134,7 @@ public void testAllTypesParameterMetadata_GoogleSql() throws SQLException {
         assertEquals(Types.ARRAY, metadata.getParameterType(++index));
         assertEquals("ARRAY<TIMESTAMP>", metadata.getParameterTypeName(index));
       }
+      assertEquals(1, mockSpanner.countRequestsOfType(ExecuteSqlRequest.class));
     }
   }
 
@@ -214,6 +216,36 @@ public void testAllTypesParameterMetadata_PostgreSQL() throws SQLException {
         assertEquals(Types.ARRAY, metadata.getParameterType(++index));
         assertEquals("timestamp with time zone[]", metadata.getParameterTypeName(index));
       }
+      assertEquals(1, mockSpanner.countRequestsOfType(ExecuteSqlRequest.class));
+    }
+  }
+
+  @Test
+  public void testSimpleJdbcParameterMetadata() throws SQLException {
+    mockSpanner.putStatementResult(
+        MockSpannerServiceImpl.StatementResult.detectDialectResult(Dialect.GOOGLE_STANDARD_SQL));
+    String baseSql =
+        "insert into all_types (col_bool, col_bytes, col_date, col_float32, col_float64, col_int64, "
+            + "col_json, col_numeric, col_string, col_timestamp, col_bool_array, col_bytes_array, "
+            + "col_date_array, col_float32_array, col_float64_array, col_int64_array, col_json_array,"
+            + "col_numeric_array, col_string_array, col_timestamp_array) values (%s)";
+    String jdbcSql =
+        String.format(
+            baseSql,
+            IntStream.range(0, 20).mapToObj(ignored -> "?").collect(Collectors.joining(", ")));
+
+    System.setProperty(JdbcSimpleParameterMetaData.USE_SIMPLE_PARAMETER_METADATA_KEY, "true");
+    try (Connection connection = createJdbcConnection()) {
+      try (PreparedStatement statement = connection.prepareStatement(jdbcSql)) {
+        ParameterMetaData metadata = statement.getParameterMetaData();
+        assertEquals(20, metadata.getParameterCount());
+        for (int i = 0; i < metadata.getParameterCount(); i++) {
+          assertEquals(Types.OTHER, metadata.getParameterType(i));
+        }
+      }
+      assertEquals(0, mockSpanner.countRequestsOfType(ExecuteSqlRequest.class));
+    } finally {
+      System.clearProperty(JdbcSimpleParameterMetaData.USE_SIMPLE_PARAMETER_METADATA_KEY);
     }
   }