feat: Last statement sample

samples/snippets/src/main/java/com/example/spanner/LastStatementSample.java

@@ -0,0 +1,69 @@
+/*
+ * 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.example.spanner;
+
+import com.google.cloud.spanner.DatabaseClient;
+import com.google.cloud.spanner.DatabaseId;
+import com.google.cloud.spanner.Options;
+import com.google.cloud.spanner.Spanner;
+import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.Statement;
+
+/**
+ * Sample showing how to set the last statement option when a DML statement is the last statement in a transaction.
+ */
+public class LastStatementSample {
+
+    static void insertAndUpdateUsingLastStatement() {
+        // TODO(developer): Replace these variables before running the sample.
+        final String projectId = "my-project";
+        final String instanceId = "my-instance";
+        final String databaseId = "my-database";
+
+        try (Spanner spanner =
+                     SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
+            final DatabaseClient databaseClient =
+                    spanner.getDatabaseClient(DatabaseId.of(projectId, instanceId, databaseId));
+            insertAndUpdateUsingLastStatement(databaseClient);
+        }
+    }
+
+    // [START spanner_last_statement]
+    static void insertAndUpdateUsingLastStatement(DatabaseClient client) {
+        client
+                .readWriteTransaction()
+                .run(
+                        transaction -> {
+                            transaction.executeUpdate(
+                                    Statement.of(
+                                            "INSERT Singers (SingerId, FirstName, LastName)\n"
+                                                    + "VALUES (54213, 'John', 'Do')"));
+                            System.out.println("New singer inserted.");
+
+                            // Pass in the `lastStatement` option to the last DML statement of the transaction.
+                            transaction.executeUpdate(
+                                    Statement.of(
+                                            "UPDATE Singers SET Singers.LastName = 'Doe' WHERE SingerId = 54213\n"),
+                                    Options.lastStatement());
+                            System.out.println("Singer last name updated.");
+
+                            return null;
+                        });
+    }
+    // [END spanner_last_statement]
+
+}

samples/snippets/src/main/java/com/example/spanner/PgLastStatementSample.java

@@ -0,0 +1,69 @@
+/*
+ * 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.example.spanner;
+
+import com.google.cloud.spanner.DatabaseClient;
+import com.google.cloud.spanner.DatabaseId;
+import com.google.cloud.spanner.Options;
+import com.google.cloud.spanner.Spanner;
+import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.Statement;
+
+/**
+ * Sample showing how to set the last statement option when a DML statement is the last statement in a transaction.
+ */
+public class PgLastStatementSample {
+
+    static void insertAndUpdateUsingLastStatement() {
+        // TODO(developer): Replace these variables before running the sample.
+        final String projectId = "my-project";
+        final String instanceId = "my-instance";
+        final String databaseId = "my-database";
+
+        try (Spanner spanner =
+                     SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
+            final DatabaseClient databaseClient =
+                    spanner.getDatabaseClient(DatabaseId.of(projectId, instanceId, databaseId));
+            insertAndUpdateUsingLastStatement(databaseClient);
+        }
+    }
+
+    // [START spanner_postgresql_last_statement]
+    static void insertAndUpdateUsingLastStatement(DatabaseClient client) {
+        client
+                .readWriteTransaction()
+                .run(
+                        transaction -> {
+                            transaction.executeUpdate(
+                                    Statement.of(
+                                            "INSERT INTO Singers (SingerId, FirstName, LastName) "
+                                                    + "VALUES (54214, 'John', 'Do')"));
+                            System.out.println("New singer inserted.");
+
+                            // Pass in the `lastStatement` option to the last DML statement of the transaction.
+                            transaction.executeUpdate(
+                                    Statement.of(
+                                            "UPDATE Singers SET LastName = 'Doe' WHERE SingerId = 54214\n"),
+                                    Options.lastStatement());
+                            System.out.println("Singer last name updated.");
+
+                            return null;
+                        });
+    }
+    // [END spanner_postgresql_last_statement]
+
+}

samples/snippets/src/test/java/com/example/spanner/LastStatementSampleIT.java

@@ -0,0 +1,69 @@
+/*
+ * 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.example.spanner;
+
+import static com.example.spanner.SampleRunner.runSample;
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.cloud.spanner.DatabaseClient;
+import com.google.cloud.spanner.DatabaseId;
+import com.google.cloud.spanner.KeySet;
+import com.google.cloud.spanner.Mutation;
+import com.google.common.collect.ImmutableList;
+import java.util.Arrays;
+import java.util.Collections;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Integration tests for {@link LastStatementSample} */
+@RunWith(JUnit4.class)
+public class LastStatementSampleIT extends SampleTestBase {
+
+    private static DatabaseId databaseId;
+
+    @BeforeClass
+    public static void createTestDatabase() throws Exception {
+        final String database = idGenerator.generateDatabaseId();
+        databaseAdminClient
+                .createDatabase(
+                        instanceId,
+                        database,
+                        ImmutableList.of(
+                                "CREATE TABLE Singers ("
+                                        + "  SingerId   INT64 NOT NULL,"
+                                        + "  FirstName  STRING(1024),"
+                                        + "  LastName   STRING(1024),"
+                                        + "  SingerInfo BYTES(MAX)"
+                                        + ") PRIMARY KEY (SingerId)"))
+                .get();
+        databaseId = DatabaseId.of(projectId, instanceId, database);
+    }
+
+    @Test
+    public void testSetLastStatementOptionSample() throws Exception {
+        final DatabaseClient client = spanner.getDatabaseClient(databaseId);
+        String out =
+                runSample(
+                        () -> LastStatementSample.insertAndUpdateUsingLastStatement(client));
+        assertThat(out).contains("New singer inserted.");
+        assertThat(out).contains("Singer last name updated.");
+    }
+}

samples/snippets/src/test/java/com/example/spanner/PgLastStatementSampleIT.java

@@ -0,0 +1,80 @@
+/*
+ * 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.example.spanner;
+
+import static com.example.spanner.SampleRunner.runSample;
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.api.gax.longrunning.OperationFuture;
+import com.google.cloud.spanner.DatabaseClient;
+import com.google.cloud.spanner.DatabaseId;
+import com.google.cloud.spanner.Dialect;
+import com.google.cloud.spanner.KeySet;
+import com.google.cloud.spanner.Mutation;
+import com.google.common.collect.ImmutableList;
+import com.google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.concurrent.TimeUnit;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Integration tests for {@link PgLastStatementSample} */
+@RunWith(JUnit4.class)
+public class PgLastStatementSampleIT extends SampleTestBase {
+
+    private static DatabaseId databaseId;
+
+    @BeforeClass
+    public static void createTestDatabase() throws Exception {
+        final String database = idGenerator.generateDatabaseId();
+        databaseAdminClient
+                .createDatabase(
+                        databaseAdminClient
+                                .newDatabaseBuilder(DatabaseId.of(projectId, instanceId, database))
+                                .setDialect(Dialect.POSTGRESQL)
+                                .build(),
+                        Collections.emptyList())
+                .get(10, TimeUnit.MINUTES);
+        final OperationFuture<Void, UpdateDatabaseDdlMetadata> updateOperation =
+                databaseAdminClient.updateDatabaseDdl(
+                        instanceId,
+                        database,
+                        ImmutableList.of(
+                                "CREATE TABLE Singers ("
+                                        + "  SingerId   bigint NOT NULL,"
+                                        + "  FirstName  character varying(1024),"
+                                        + "  LastName   character varying(1024),"
+                                        + "  PRIMARY KEY (SingerId)"
+                                        + ")"),
+                        null);
+        updateOperation.get(10, TimeUnit.MINUTES);
+        databaseId = DatabaseId.of(projectId, instanceId, database);
+    }
+
+    @Test
+    public void testSetLastStatementOptionSample() throws Exception {
+        final DatabaseClient client = spanner.getDatabaseClient(databaseId);
+        String out =
+                runSample(
+                        () -> PgLastStatementSample.insertAndUpdateUsingLastStatement(client));
+        assertThat(out).contains("New singer inserted.");
+        assertThat(out).contains("Singer last name updated.");
+    }
+}