From aeb255d2e5998ebb6f3eb7f655f63c957d5d92bd Mon Sep 17 00:00:00 2001
From: Thiago Nunes <thiagotnunes@google.com>
Date: Wed, 6 Jan 2021 09:33:52 +1100
Subject: [PATCH] docs: documents resume on update database ddl (#767)

Instead of throwing an ALREADY_EXISTS error on the update database ddl
operation, we resume the original operation. This is necessary, because
the update database ddl is retryable. Because of this, we don't want to
confuse the caller by bubbling up an ALREADY_EXISTS error on a retry,
even though they used a non-existing operation id.
---
 .../com/google/cloud/spanner/DatabaseAdminClient.java |  5 +++++
 .../google/cloud/spanner/spi/v1/GapicSpannerRpc.java  | 11 +++++++++++
 2 files changed, 16 insertions(+)

diff --git a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java
index ed736b92ad..e7a8ed6787 100644
--- a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java
+++ b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java
@@ -172,6 +172,11 @@ public OperationFuture<Database, RestoreDatabaseMetadata> restoreDatabase(
    * problem like a `NULL` value in a column to which `NOT NULL` would be added). If a statement
    * fails, all subsequent statements in the batch are automatically cancelled.
    *
+   * <p>If an operation already exists with the given operation id, the operation will be resumed
+   * and the returned future will complete when the original operation finishes. See more
+   * information in {@link com.google.cloud.spanner.spi.v1.GapicSpannerRpc#updateDatabaseDdl(String,
+   * Iterable, String)}
+   *
    * <p>Example to update the database DDL.
    *
    * <pre>{@code
diff --git a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java
index ddd45dd239..efa07fc961 100644
--- a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java
+++ b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java
@@ -1037,6 +1037,17 @@ public Timestamp apply(Operation input) {
         NanoClock.getDefaultClock());
   }
 
+  /**
+   * If the update database ddl operation returns an ALREADY_EXISTS error, meaning the operation id
+   * used is already in flight, this method will simply resume the original operation. The returned
+   * future will be completed when the original operation finishes.
+   *
+   * <p>This mechanism is necessary, because the update database ddl can be retried. If a retryable
+   * failure occurs, the backend has already started processing the update database ddl operation
+   * with the given id and the library issues a retry, an ALREADY_EXISTS error will be returned. If
+   * we were to bubble this error up, it would be confusing for the caller, who used originally
+   * called the method with a new operation id.
+   */
   @Override
   public OperationFuture<Empty, UpdateDatabaseDdlMetadata> updateDatabaseDdl(
       final String databaseName,