From 5fda1693a95d1addc55bbbd164bc06e741ffdad9 Mon Sep 17 00:00:00 2001
From: Thiago Nunes <thiagotnunes@google.com>
Date: Tue, 5 Jan 2021 15:49:04 +1100
Subject: [PATCH] docs: documents resume on update database ddl

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 ed736b92ad6..e7a8ed67871 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 ddd45dd2392..efa07fc9618 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,