chore: add unknownLength connection property (#4223)

* chore: add unknownLength connection property

Add an unknownLength connection property that can be used to determine what length should
be returned by a driver when it is requested to return the length of a data type without a
known length.

This is similar to the unknownLength connection parameter implemented by the PostgreSQL
JDBC driver: https://jdbc.postgresql.org/documentation/use/#connection-parameters

* chore: generate libraries at Fri Nov 14 10:56:58 UTC 2025

---------

Co-authored-by: cloud-java-bot <[email protected]>

Author: olavloite

google-cloud-spanner/clirr-ignored-differences.xml

@@ -1057,4 +1057,9 @@
     <differenceType>8001</differenceType>
     <className>com/google/cloud/spanner/LatencyTest</className>
   </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>java.lang.Object getConnectionPropertyValue(com.google.cloud.spanner.connection.ConnectionProperty)</method>
+  </difference>
 </differences>

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/Connection.java

@@ -189,6 +189,10 @@ public interface Connection extends AutoCloseable {
    */
   void reset();
 
+  /** Returns the current value of the given connection property. */
+  <T> T getConnectionPropertyValue(
+      com.google.cloud.spanner.connection.ConnectionProperty<T> property);
+
   /**
    * Sets autocommit on/off for this {@link Connection}. Connections in autocommit mode will apply
    * any changes to the database directly without waiting for an explicit commit. DDL- and DML

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionImpl.java

@@ -574,7 +574,8 @@ public boolean isClosed() {
     return closed;
   }
 
-  private <T> T getConnectionPropertyValue(
+  @Override
+  public <T> T getConnectionPropertyValue(
       com.google.cloud.spanner.connection.ConnectionProperty<T> property) {
     return this.connectionState.getValue(property).getValue();
   }

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionProperties.java

@@ -766,6 +766,18 @@ public class ConnectionProperties {
           DEFAULT_BATCH_DML_UPDATE_COUNT,
           LongConverter.INSTANCE,
           Context.USER);
+  public static final ConnectionProperty<Integer> UNKNOWN_LENGTH =
+      create(
+          "unknownLength",
+          "Spanner does not return the length of the selected columns in query results. When"
+              + " returning meta-data about these columns through functions like"
+              + " ResultSetMetaData.getColumnDisplaySize and ResultSetMetaData.getPrecision, we"
+              + " must provide a value. Various client tools and applications have different ideas"
+              + " about what they would like to see. This property specifies the length to return"
+              + " for types of unknown length.",
+          /* defaultValue= */ 50,
+          NonNegativeIntegerConverter.INSTANCE,
+          Context.USER);
 
   static final ImmutableMap<String, ConnectionProperty<?>> CONNECTION_PROPERTIES =
       CONNECTION_PROPERTIES_BUILDER.build();

google-cloud-spanner/src/test/java/com/google/cloud/spanner/connection/ConnectionStateMockServerTest.java

@@ -291,4 +291,13 @@ public void testSetLocalInvalidValue() {
       assertTrue(connection.isRetryAbortsInternally());
     }
   }
+
+  @Test
+  public void testGetConnectionProperty() {
+    try (Connection connection = createConnection()) {
+      ConnectionProperty<Integer> unknownLength = ConnectionProperties.UNKNOWN_LENGTH;
+      assertEquals(
+          unknownLength.getDefaultValue(), connection.getConnectionPropertyValue(unknownLength));
+    }
+  }
 }