docs: update README and latency guide

Author: olavloite

README.md

@@ -109,6 +109,7 @@ See [Supported Connection Properties](documentation/connection_properties.md) fo
 supported connection properties.
 
 #### Commonly Used Properties
+- default_isolation_level (String): Spanner supports isolation levels REPEATABLE_READ or SERIALIZABLE. SERIALIZABLE is the default. Using isolation level REPEATABLE_READ improves performance by reducing the amount of locks that are taken by transactions that execute a large number of queries in read/write transactions. See https://cloud.google.com/spanner/docs/isolation-levels for more information on the supported isolation levels in Spanner.
 - credentials (String): URL for the credentials file to use for the connection. If you do not specify any credentials at all, the default credentials of the environment as returned by `GoogleCredentials#getApplicationDefault()` is used. Example: `jdbc:cloudspanner:/projects/my-project/instances/my-instance/databases/my-db;credentials=/path/to/credentials.json`
 - autocommit (boolean): Sets the initial autocommit mode for the connection. Default is true.
 - readonly (boolean): Sets the initial readonly mode for the connection. Default is false.

documentation/latency-debugging-guide.md

@@ -5,6 +5,43 @@ queries and transactions and to determine whether transactions or requests are b
 addition, all metrics described in [Latency points in a Spanner request](https://cloud.google.com/spanner/docs/latency-points)
 are also collected by the JDBC driver and can be used for debugging.
 
+## Isolation Level
+
+A common reason for high latency in read/write transactions is lock contention. Spanner by default
+uses isolation level `SERIALIZABLE`. This causes all queries in read/write transactions to take
+locks for all rows that are scanned by a query. Using isolation level `REPEATABLE_READ` reduces the
+number of locks that are taken during a read/write transaction, and can significantly improve
+performance for applications that execute many and/or large queries in read/write transactions.
+
+Enable isolation level `REPEATABLE_READ` by default for all transactions that are executed by the
+JDBC driver by setting the `default_isolation_level` connection property like this in the connection
+URL:
+
+```java
+String projectId = "my-project";
+String instanceId = "my-instance";
+String databaseId = "my-database";
+String isolationLevel = "REPEATABLE_READ";
+
+try (Connection connection =
+    DriverManager.getConnection(
+        String.format(
+            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s?default_isolation_level=%s",
+            projectId, instanceId, databaseId, isolationLevel))) {
+  try (Statement statement = connection.createStatement()) {
+    try (ResultSet rs = statement.executeQuery("SELECT CURRENT_TIMESTAMP()")) {
+      while (rs.next()) {
+        System.out.printf(
+            "Connected to Cloud Spanner at [%s]%n", rs.getTimestamp(1).toString());
+      }
+    }
+  }
+}
+```
+
+See https://cloud.google.com/spanner/docs/isolation-levels for more information on the supported
+isolation levels in Spanner.
+
 ## Configuration
 
 You can configure the OpenTelemetry instance that should be used in two ways:

samples/snippets/pom.xml

@@ -23,13 +23,6 @@
   <!-- [START spanner-jdbc_install_with_bom] -->
   <dependencyManagement>
     <dependencies>
-      <dependency>
-        <groupId>com.google.cloud</groupId>
-        <artifactId>google-cloud-spanner-bom</artifactId>
-        <version>6.91.1</version>
-        <type>pom</type>
-        <scope>import</scope>
-      </dependency>
       <dependency>
         <groupId>com.google.cloud</groupId>
         <artifactId>libraries-bom</artifactId>
@@ -44,7 +37,6 @@
     <dependency>
       <groupId>com.google.cloud</groupId>
       <artifactId>google-cloud-spanner-jdbc</artifactId>
-      <version>2.29.1</version>
       <exclusions>
         <exclusion>
           <groupId>com.google.api.grpc</groupId>

src/test/java/com/google/cloud/spanner/jdbc/JdbcTransactionOptionsTest.java

@@ -27,10 +27,15 @@
 import com.google.cloud.spanner.connection.AbstractMockServerTest;
 import com.google.cloud.spanner.connection.SpannerPool;
 import com.google.spanner.v1.CommitRequest;
+import com.google.spanner.v1.ExecuteSqlRequest;
+import com.google.spanner.v1.TransactionOptions.IsolationLevel;
+import java.sql.Connection;
 import java.sql.DriverManager;
 import java.sql.ResultSet;
 import java.sql.SQLException;
 import java.time.Duration;
+import java.util.Arrays;
+import java.util.stream.Collectors;
 import org.junit.After;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -138,4 +143,63 @@ public void testMaxCommitDelay() throws SQLException {
       assertEquals(Duration.ofMillis(50).toNanos(), request.getMaxCommitDelay().getNanos());
     }
   }
+
+  @Test
+  public void testDefaultIsolationLevel() throws SQLException {
+    for (IsolationLevel isolationLevel :
+        Arrays.stream(IsolationLevel.values())
+            .filter(level -> !level.equals(IsolationLevel.UNRECOGNIZED))
+            .collect(Collectors.toList())) {
+      try (java.sql.Connection connection =
+          DriverManager.getConnection(
+              "jdbc:" + getBaseUrl() + ";default_isolation_level=" + isolationLevel.name())) {
+        connection.setAutoCommit(false);
+        try (ResultSet resultSet =
+            connection.createStatement().executeQuery(SELECT1_STATEMENT.getSql())) {
+          while (resultSet.next()) {
+            // ignore
+          }
+        }
+        connection.commit();
+        assertEquals(1, mockSpanner.countRequestsOfType(ExecuteSqlRequest.class));
+        ExecuteSqlRequest request = mockSpanner.getRequestsOfType(ExecuteSqlRequest.class).get(0);
+        assertTrue(request.hasTransaction());
+        assertTrue(request.getTransaction().hasBegin());
+        assertTrue(request.getTransaction().getBegin().hasReadWrite());
+        assertEquals(isolationLevel, request.getTransaction().getBegin().getIsolationLevel());
+        assertEquals(1, mockSpanner.countRequestsOfType(CommitRequest.class));
+
+        mockSpanner.clearRequests();
+      }
+    }
+  }
+
+  @Test
+  public void testSetIsolationLevel() throws SQLException {
+    try (java.sql.Connection connection = createJdbcConnection()) {
+      connection.setAutoCommit(false);
+      for (int isolationLevel :
+          new int[] {Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE}) {
+        connection.setTransactionIsolation(isolationLevel);
+        try (ResultSet resultSet =
+            connection.createStatement().executeQuery(SELECT1_STATEMENT.getSql())) {
+          while (resultSet.next()) {
+            // ignore
+          }
+        }
+        connection.commit();
+        assertEquals(1, mockSpanner.countRequestsOfType(ExecuteSqlRequest.class));
+        ExecuteSqlRequest request = mockSpanner.getRequestsOfType(ExecuteSqlRequest.class).get(0);
+        assertTrue(request.hasTransaction());
+        assertTrue(request.getTransaction().hasBegin());
+        assertTrue(request.getTransaction().getBegin().hasReadWrite());
+        assertEquals(
+            IsolationLevelConverter.convertToSpanner(isolationLevel),
+            request.getTransaction().getBegin().getIsolationLevel());
+        assertEquals(1, mockSpanner.countRequestsOfType(CommitRequest.class));
+
+        mockSpanner.clearRequests();
+      }
+    }
+  }
 }