feat: automatically set default sequence kind in JDBC and PGAdapter (#3658)

* feat: automatically set default sequence kind in JDBC and PGAdapter

Add a connection property that automatically sets the default sequence kind for
a database if a DDL statement fails due to no default sequence kind having been
set. This allows tools like PGAdapter and ORMs that use JDBC to automatically
use auto_increment columns without the need to add an ALTER DATABASE statement.

* chore: fix clirr failures

* test: fix integration test

* fix: correctly retry if a failure happens in the middle

Author: olavloite

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

@@ -828,4 +828,16 @@
     <className>com/google/cloud/spanner/SpannerOptions$SpannerEnvironment</className>
     <method>com.google.auth.oauth2.GoogleCredentials getDefaultExternalHostCredentials()</method>
   </difference>
+
+  <!-- Default sequence kind -->
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>void setDefaultSequenceKind(java.lang.String)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>java.lang.String getDefaultSequenceKind()</method>
+  </difference>
 </differences>

google-cloud-spanner/src/main/java/com/google/cloud/spanner/MissingDefaultSequenceKindException.java

@@ -0,0 +1,52 @@
+/*
+ * 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;
+
+import com.google.api.gax.rpc.ApiException;
+import java.util.regex.Pattern;
+import javax.annotation.Nullable;
+
+/**
+ * Exception thrown by Spanner when a DDL statement failed because no default sequence kind has been
+ * configured for a database.
+ */
+public class MissingDefaultSequenceKindException extends SpannerException {
+  private static final long serialVersionUID = 1L;
+
+  private static final Pattern PATTERN =
+      Pattern.compile(
+          "The sequence kind of an identity column .+ is not specified\\. Please specify the sequence kind explicitly or set the database option `default_sequence_kind`\\.");
+
+  /** Private constructor. Use {@link SpannerExceptionFactory} to create instances. */
+  MissingDefaultSequenceKindException(
+      DoNotConstructDirectly token,
+      ErrorCode errorCode,
+      String message,
+      Throwable cause,
+      @Nullable ApiException apiException) {
+    super(token, errorCode, /*retryable = */ false, message, cause, apiException);
+  }
+
+  static boolean isMissingDefaultSequenceKindException(Throwable cause) {
+    if (cause == null
+        || cause.getMessage() == null
+        || !PATTERN.matcher(cause.getMessage()).find()) {
+      return false;
+    }
+    return true;
+  }
+}

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerExceptionFactory.java

@@ -16,6 +16,7 @@
 
 package com.google.cloud.spanner;
 
+import static com.google.cloud.spanner.MissingDefaultSequenceKindException.isMissingDefaultSequenceKindException;
 import static com.google.cloud.spanner.TransactionMutationLimitExceededException.isTransactionMutationLimitException;
 
 import com.google.api.gax.grpc.GrpcStatusCode;
@@ -336,6 +337,9 @@ static SpannerException newSpannerExceptionPreformatted(
           return new TransactionMutationLimitExceededException(
               token, code, message, cause, apiException);
         }
+        if (isMissingDefaultSequenceKindException(apiException)) {
+          return new MissingDefaultSequenceKindException(token, code, message, cause, apiException);
+        }
         // Fall through to the default.
       default:
         return new SpannerException(

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

@@ -862,6 +862,18 @@ interface TransactionCallable<T> {
   /** Sets how the connection should behave if a DDL statement is executed during a transaction. */
   void setDdlInTransactionMode(DdlInTransactionMode ddlInTransactionMode);
 
+  /**
+   * Returns the default sequence kind that will be set for this database if a DDL statement is
+   * executed that uses auto_increment or serial.
+   */
+  String getDefaultSequenceKind();
+
+  /**
+   * Sets the default sequence kind that will be set for this database if a DDL statement is
+   * executed that uses auto_increment or serial.
+   */
+  void setDefaultSequenceKind(String defaultSequenceKind);
+
   /**
    * Creates a savepoint with the given name.
    *

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

@@ -27,6 +27,7 @@
 import static com.google.cloud.spanner.connection.ConnectionProperties.AUTO_PARTITION_MODE;
 import static com.google.cloud.spanner.connection.ConnectionProperties.DATA_BOOST_ENABLED;
 import static com.google.cloud.spanner.connection.ConnectionProperties.DDL_IN_TRANSACTION_MODE;
+import static com.google.cloud.spanner.connection.ConnectionProperties.DEFAULT_SEQUENCE_KIND;
 import static com.google.cloud.spanner.connection.ConnectionProperties.DELAY_TRANSACTION_START_UNTIL_FIRST_WRITE;
 import static com.google.cloud.spanner.connection.ConnectionProperties.DIRECTED_READ;
 import static com.google.cloud.spanner.connection.ConnectionProperties.KEEP_TRANSACTION_ALIVE;
@@ -761,6 +762,16 @@ public void setDdlInTransactionMode(DdlInTransactionMode ddlInTransactionMode) {
     setConnectionPropertyValue(DDL_IN_TRANSACTION_MODE, ddlInTransactionMode);
   }
 
+  @Override
+  public String getDefaultSequenceKind() {
+    return getConnectionPropertyValue(DEFAULT_SEQUENCE_KIND);
+  }
+
+  @Override
+  public void setDefaultSequenceKind(String defaultSequenceKind) {
+    setConnectionPropertyValue(DEFAULT_SEQUENCE_KIND, defaultSequenceKind);
+  }
+
   @Override
   public void setStatementTimeout(long timeout, TimeUnit unit) {
     Preconditions.checkArgument(timeout > 0L, "Zero or negative timeout values are not allowed");
@@ -2152,13 +2163,9 @@ UnitOfWork createNewUnitOfWork(
               .setDdlClient(ddlClient)
               .setDatabaseClient(dbClient)
               .setBatchClient(batchClient)
-              .setReadOnly(getConnectionPropertyValue(READONLY))
-              .setReadOnlyStaleness(getConnectionPropertyValue(READ_ONLY_STALENESS))
-              .setAutocommitDmlMode(getConnectionPropertyValue(AUTOCOMMIT_DML_MODE))
+              .setConnectionState(connectionState)
               .setTransactionRetryListeners(transactionRetryListeners)
-              .setReturnCommitStats(getConnectionPropertyValue(RETURN_COMMIT_STATS))
               .setExcludeTxnFromChangeStreams(excludeTxnFromChangeStreams)
-              .setMaxCommitDelay(getConnectionPropertyValue(MAX_COMMIT_DELAY))
               .setStatementTimeout(statementTimeout)
               .withStatementExecutor(statementExecutor)
               .setSpan(
@@ -2230,6 +2237,7 @@ UnitOfWork createNewUnitOfWork(
               .withStatementExecutor(statementExecutor)
               .setSpan(createSpanForUnitOfWork(DDL_BATCH))
               .setProtoDescriptors(getProtoDescriptors())
+              .setConnectionState(connectionState)
               .build();
         default:
       }

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

@@ -242,6 +242,7 @@ public String[] getValidValues() {
   static final RpcPriority DEFAULT_RPC_PRIORITY = null;
   static final DdlInTransactionMode DEFAULT_DDL_IN_TRANSACTION_MODE =
       DdlInTransactionMode.ALLOW_IN_EMPTY_TRANSACTION;
+  static final String DEFAULT_DEFAULT_SEQUENCE_KIND = null;
   static final boolean DEFAULT_RETURN_COMMIT_STATS = false;
   static final boolean DEFAULT_LENIENT = false;
   static final boolean DEFAULT_ROUTE_TO_LEADER = true;
@@ -324,6 +325,7 @@ public String[] getValidValues() {
   public static final String RPC_PRIORITY_NAME = "rpcPriority";
 
   public static final String DDL_IN_TRANSACTION_MODE_PROPERTY_NAME = "ddlInTransactionMode";
+  public static final String DEFAULT_SEQUENCE_KIND_PROPERTY_NAME = "defaultSequenceKind";
   /** Dialect to use for a connection. */
   static final String DIALECT_PROPERTY_NAME = "dialect";
   /** Name of the 'databaseRole' connection property. */

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

@@ -41,6 +41,7 @@
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_DATABASE_ROLE;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_DATA_BOOST_ENABLED;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_DDL_IN_TRANSACTION_MODE;
+import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_DEFAULT_SEQUENCE_KIND;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_DELAY_TRANSACTION_START_UNTIL_FIRST_WRITE;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_ENABLE_API_TRACING;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_ENABLE_END_TO_END_TRACING;
@@ -61,6 +62,7 @@
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_RETURN_COMMIT_STATS;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_ROUTE_TO_LEADER;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_RPC_PRIORITY;
+import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_SEQUENCE_KIND_PROPERTY_NAME;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_TRACK_CONNECTION_LEAKS;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_TRACK_SESSION_LEAKS;
 import static com.google.cloud.spanner.connection.ConnectionOptions.DEFAULT_USER_AGENT;
@@ -531,6 +533,15 @@ public class ConnectionProperties {
           DdlInTransactionMode.values(),
           DdlInTransactionModeConverter.INSTANCE,
           Context.USER);
+  static final ConnectionProperty<String> DEFAULT_SEQUENCE_KIND =
+      create(
+          DEFAULT_SEQUENCE_KIND_PROPERTY_NAME,
+          "The default sequence kind that should be used for the database. "
+              + "This property is only used when a DDL statement that requires a default "
+              + "sequence kind is executed on this connection.",
+          DEFAULT_DEFAULT_SEQUENCE_KIND,
+          StringValueConverter.INSTANCE,
+          Context.USER);
   static final ConnectionProperty<Duration> MAX_COMMIT_DELAY =
       create(
           "maxCommitDelay",
@@ -615,16 +626,10 @@ private static <T> ConnectionProperty<T> create(
       T[] validValues,
       ClientSideStatementValueConverter<T> converter,
       Context context) {
-    try {
-      ConnectionProperty<T> property =
-          ConnectionProperty.create(
-              name, description, defaultValue, validValues, converter, context);
-      CONNECTION_PROPERTIES_BUILDER.put(property.getKey(), property);
-      return property;
-    } catch (Throwable t) {
-      t.printStackTrace();
-    }
-    return null;
+    ConnectionProperty<T> property =
+        ConnectionProperty.create(name, description, defaultValue, validValues, converter, context);
+    CONNECTION_PROPERTIES_BUILDER.put(property.getKey(), property);
+    return property;
   }
 
   /** Parse the connection properties that can be found in the given connection URL. */

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

@@ -17,6 +17,7 @@
 package com.google.cloud.spanner.connection;
 
 import static com.google.cloud.spanner.connection.AbstractStatementParser.RUN_BATCH_STATEMENT;
+import static com.google.cloud.spanner.connection.ConnectionProperties.DEFAULT_SEQUENCE_KIND;
 
 import com.google.api.core.ApiFuture;
 import com.google.api.core.ApiFutures;
@@ -45,6 +46,7 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.concurrent.Callable;
+import java.util.concurrent.atomic.AtomicReference;
 import javax.annotation.Nonnull;
 
 /**
@@ -61,11 +63,13 @@ class DdlBatch extends AbstractBaseUnitOfWork {
   private final List<String> statements = new ArrayList<>();
   private UnitOfWorkState state = UnitOfWorkState.STARTED;
   private final byte[] protoDescriptors;
+  private final ConnectionState connectionState;
 
   static class Builder extends AbstractBaseUnitOfWork.Builder<Builder, DdlBatch> {
     private DdlClient ddlClient;
     private DatabaseClient dbClient;
     private byte[] protoDescriptors;
+    private ConnectionState connectionState;
 
     private Builder() {}
 
@@ -86,6 +90,11 @@ Builder setProtoDescriptors(byte[] protoDescriptors) {
       return this;
     }
 
+    Builder setConnectionState(ConnectionState connectionState) {
+      this.connectionState = connectionState;
+      return this;
+    }
+
     @Override
     DdlBatch build() {
       Preconditions.checkState(ddlClient != null, "No DdlClient specified");
@@ -103,6 +112,7 @@ private DdlBatch(Builder builder) {
     this.ddlClient = builder.ddlClient;
     this.dbClient = builder.dbClient;
     this.protoDescriptors = builder.protoDescriptors;
+    this.connectionState = Preconditions.checkNotNull(builder.connectionState);
   }
 
   @Override
@@ -235,17 +245,28 @@ public ApiFuture<long[]> runBatchAsync(CallType callType) {
       Callable<long[]> callable =
           () -> {
             try {
-              OperationFuture<Void, UpdateDatabaseDdlMetadata> operation =
-                  ddlClient.executeDdl(statements, protoDescriptors);
+              AtomicReference<OperationFuture<Void, UpdateDatabaseDdlMetadata>> operationReference =
+                  new AtomicReference<>();
               try {
-                // Wait until the operation has finished.
-                getWithStatementTimeout(operation, RUN_BATCH_STATEMENT);
+                ddlClient.runWithRetryForMissingDefaultSequenceKind(
+                    restartIndex -> {
+                      OperationFuture<Void, UpdateDatabaseDdlMetadata> operation =
+                          ddlClient.executeDdl(
+                              statements.subList(restartIndex, statements.size()),
+                              protoDescriptors);
+                      operationReference.set(operation);
+                      // Wait until the operation has finished.
+                      getWithStatementTimeout(operation, RUN_BATCH_STATEMENT);
+                    },
+                    connectionState.getValue(DEFAULT_SEQUENCE_KIND).getValue(),
+                    dbClient.getDialect(),
+                    operationReference);
                 long[] updateCounts = new long[statements.size()];
                 Arrays.fill(updateCounts, 1L);
                 state = UnitOfWorkState.RAN;
                 return updateCounts;
               } catch (SpannerException e) {
-                long[] updateCounts = extractUpdateCounts(operation);
+                long[] updateCounts = extractUpdateCounts(operationReference.get());
                 throw SpannerExceptionFactory.newSpannerBatchUpdateException(
                     e.getErrorCode(), e.getMessage(), updateCounts);
               }

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

@@ -22,13 +22,18 @@
 import com.google.cloud.spanner.DatabaseId;
 import com.google.cloud.spanner.Dialect;
 import com.google.cloud.spanner.ErrorCode;
+import com.google.cloud.spanner.MissingDefaultSequenceKindException;
+import com.google.cloud.spanner.SpannerException;
 import com.google.cloud.spanner.SpannerExceptionFactory;
 import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
 import com.google.spanner.admin.database.v1.CreateDatabaseMetadata;
 import com.google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata;
 import java.util.Collections;
 import java.util.List;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
 
 /**
  * Convenience class for executing Data Definition Language statements on transactions that support
@@ -131,4 +136,46 @@ static boolean isCreateDatabaseStatement(String statement) {
         && tokens[0].equalsIgnoreCase("CREATE")
         && tokens[1].equalsIgnoreCase("DATABASE");
   }
+
+  void runWithRetryForMissingDefaultSequenceKind(
+      Consumer<Integer> runnable,
+      String defaultSequenceKind,
+      Dialect dialect,
+      AtomicReference<OperationFuture<Void, UpdateDatabaseDdlMetadata>> operationReference) {
+    try {
+      runnable.accept(0);
+    } catch (Throwable t) {
+      SpannerException spannerException = SpannerExceptionFactory.asSpannerException(t);
+      if (!Strings.isNullOrEmpty(defaultSequenceKind)
+          && spannerException instanceof MissingDefaultSequenceKindException) {
+        setDefaultSequenceKind(defaultSequenceKind, dialect);
+        int restartIndex = 0;
+        if (operationReference.get() != null) {
+          try {
+            UpdateDatabaseDdlMetadata metadata = operationReference.get().getMetadata().get();
+            restartIndex = metadata.getCommitTimestampsCount();
+          } catch (Throwable ignore) {
+          }
+        }
+        runnable.accept(restartIndex);
+        return;
+      }
+      throw t;
+    }
+  }
+
+  private void setDefaultSequenceKind(String defaultSequenceKind, Dialect dialect) {
+    String ddl =
+        dialect == Dialect.POSTGRESQL
+            ? "alter database \"%s\" set spanner.default_sequence_kind = '%s'"
+            : "alter database `%s` set options (default_sequence_kind='%s')";
+    ddl = String.format(ddl, databaseName, defaultSequenceKind);
+    try {
+      executeDdl(ddl, null).get();
+    } catch (ExecutionException executionException) {
+      throw SpannerExceptionFactory.asSpannerException(executionException.getCause());
+    } catch (InterruptedException interruptedException) {
+      throw SpannerExceptionFactory.propagateInterrupt(interruptedException);
+    }
+  }
 }