noticket: Rename IsolationLevel.SNAPSHOT to SNAPSHOT_READ_ONLY, to have more consistent naming and prepare for SNAPSHOT_READ_WRITE support

Author: nvamelichev

aspect/src/main/java/tech/ydb/yoj/aspect/tx/YojTransactional.java

@@ -39,7 +39,7 @@
      * <li>{@code ONLINE_CONSISTENT_READ_ONLY}</li>
      * <li>{@code ONLINE_INCONSISTENT_READ_ONLY}</li>
      * <li>{@code STALE_CONSISTENT_READ_ONLY}</li>
-     * <li>{@code SNAPSHOT}</li>
+     * <li>{@code SNAPSHOT_READ_ONLY}</li>
      * </ul>
      * If transaction is not marked as {@link #readOnly() read-only}, isolation level is ignored.
      */

repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/YdbRepositoryTransaction.java

@@ -40,7 +40,6 @@
 import tech.ydb.yoj.ExperimentalApi;
 import tech.ydb.yoj.repository.BaseDb;
 import tech.ydb.yoj.repository.db.Entity;
-import tech.ydb.yoj.repository.db.IsolationLevel;
 import tech.ydb.yoj.repository.db.QueryStatsMode;
 import tech.ydb.yoj.repository.db.QueryTracingFilter;
 import tech.ydb.yoj.repository.db.QueryType;
@@ -221,7 +220,7 @@ private boolean isFinalActionNeeded(String actionName) {
             transactionLocal.log().info("No-op %s: scan tx", actionName);
             return false;
         }
-        if (options.isReadOnly() && options.getIsolationLevel() != IsolationLevel.SNAPSHOT) {
+        if (options.isReadOnly() && !options.getIsolationLevel().isSnapshot()) {
             transactionLocal.log().info("No-op %s: read-only tx @%s", actionName, options.getIsolationLevel());
             return false;
         }
@@ -263,16 +262,14 @@ private TxControl<?> getTxControl() {
             case ONLINE_CONSISTENT_READ_ONLY -> TxControl.onlineRo().setAllowInconsistentReads(false);
             case ONLINE_INCONSISTENT_READ_ONLY -> TxControl.onlineRo().setAllowInconsistentReads(true);
             case STALE_CONSISTENT_READ_ONLY -> TxControl.staleRo();
-            case SNAPSHOT -> {
+            case SNAPSHOT_READ_ONLY, SNAPSHOT -> {
                 TxControl<?> txControl = (txId != null ? TxControl.id(txId) : TxControl.snapshotRo());
                 yield txControl.setCommitTx(false);
             }
         };
     }
 
     private String getYql(Statement<?, ?> statement) {
-        // TODO(nvamelichev): Make the use of syntax_v1 directive configurable in YdbRepository.Settings
-        // @see https://github.com/ydb-platform/yoj-project/issues/148
         return statement.getQuery(tablespace);
     }
 
@@ -612,7 +609,7 @@ public TxMode getTxMode() {
                     case ONLINE_CONSISTENT_READ_ONLY -> TxMode.ONLINE_RO;
                     case ONLINE_INCONSISTENT_READ_ONLY -> TxMode.ONLINE_INCONSISTENT_RO;
                     case STALE_CONSISTENT_READ_ONLY -> TxMode.STALE_RO;
-                    case SNAPSHOT -> TxMode.SNAPSHOT_RO;
+                    case SNAPSHOT_READ_ONLY, SNAPSHOT -> TxMode.SNAPSHOT_RO;
                     // TxMode.NONE corresponds to DDL statements, and we have no DDL statements in YOJ transactions
                 };
             }

repository-ydb-v2/src/test/java/tech/ydb/yoj/repository/ydb/YdbRepositoryIntegrationTest.java

@@ -339,7 +339,7 @@ public void snapshotTransactionLevel() {
         assertThat(actual2).isEqualTo(expected2);
 
         db.readOnly()
-                .withStatementIsolationLevel(IsolationLevel.SNAPSHOT)
+                .withStatementIsolationLevel(IsolationLevel.SNAPSHOT_READ_ONLY)
                 .run(() -> {
                     Project actualSnapshot1 = db.projects().find(expected1.getId());
                     assertThat(actualSnapshot1).isEqualTo(expected1);
@@ -1040,7 +1040,7 @@ public void ydbTransactionCompatibility() {
                 IsolationLevel.ONLINE_CONSISTENT_READ_ONLY, TxMode.ONLINE_RO,
                 IsolationLevel.ONLINE_INCONSISTENT_READ_ONLY, TxMode.ONLINE_INCONSISTENT_RO,
                 IsolationLevel.STALE_CONSISTENT_READ_ONLY, TxMode.STALE_RO,
-                IsolationLevel.SNAPSHOT, TxMode.SNAPSHOT_RO
+                IsolationLevel.SNAPSHOT_READ_ONLY, TxMode.SNAPSHOT_RO
         ).entrySet()) {
             var isolationLevel = entry.getKey();
             var txMode = entry.getValue();
@@ -1134,7 +1134,7 @@ public void queryStatsCollectionMode() {
                 .withQueryStats(QueryStatsMode.FULL)
                 .readOnly()
                 .noFirstLevelCache()
-                .withStatementIsolationLevel(IsolationLevel.SNAPSHOT)
+                .withStatementIsolationLevel(IsolationLevel.SNAPSHOT_READ_ONLY)
                 .run(() -> db.table(UniqueProject.class).query()
                         .where("id").in(List.of(
                                 new UniqueProject.Id("id501"),
@@ -1194,7 +1194,7 @@ public void customQueryTracingFilter() {
                     .noQueryTracing()
                     .readOnly()
                     .noFirstLevelCache()
-                    .withStatementIsolationLevel(IsolationLevel.SNAPSHOT);
+                    .withStatementIsolationLevel(IsolationLevel.SNAPSHOT_READ_ONLY);
             var found = txMgr2.run(() -> db.table(ToStringCountingProject.class).find(new ToStringCountingProject.Id("id3")));
             assertThat(found).isEqualTo(project3);
 

repository/src/main/java/tech/ydb/yoj/repository/db/IsolationLevel.java

@@ -10,9 +10,13 @@
  */
 public enum IsolationLevel {
     /**
-     * All transactions are serialized one-by-one. If the DB detects a write collision among
-     * several concurrent transactions, only the first one is committed.
-     * This is the strongest level. And the only level at which data changes are possible.
+     * All transactions are serialized <em>as if</em> they are executed one-by-one. If the DB detects a write collision
+     * among several concurrent transactions, only one of them is committed, and all others get a "Transaction locks
+     * invalidated" (TLI) error, represented by YOJ
+     * {@link tech.ydb.yoj.repository.db.exception.OptimisticLockException OptimisticLockException}. This causes
+     * the transaction body to be retried by the {@link TxManager transaction manager},
+     * unless the {@link TxManager#withMaxRetries(int) retry count} is exhausted.
+     * <p>This is the strongest isolation level.
      */
     SERIALIZABLE_READ_WRITE(""),
 
@@ -23,23 +27,33 @@ public enum IsolationLevel {
 
     /**
      * The most recent inconsistent state of the database. Read only.
-     * A phantom read may occurs when, in the course of a transaction, some new rows are added
-     * by another transaction to the records being read. This is the weakest level.
+     * A phantom read may occur when, during the course of a transaction, some new rows are added
+     * by another transaction to the records being read.
+     * <p>This is the weakest isolation level.
      */
     ONLINE_INCONSISTENT_READ_ONLY("OI"),
 
     /**
      * An <em>almost</em> recent consistent state of the database. Read only.
-     * This level is faster then {@code ONLINE_CONSISTENT_READ_ONLY}, but may return stale data.
+     * This level is faster than {@link #ONLINE_CONSISTENT_READ_ONLY}, but may return stale data.
      */
     STALE_CONSISTENT_READ_ONLY("SC"),
 
     /**
-     * All the read operations within a transaction access the database snapshot. Read only.
+     * @deprecated Same as {@link #SNAPSHOT_READ_ONLY}, but unfortunately named. Please use {@link #SNAPSHOT_READ_ONLY}
+     * instead; the {@code IsolationLevel.SNAPSHOT} constant will be removed in YOJ 2.9.0.
+     */
+    @Deprecated(forRemoval = true)
+    SNAPSHOT("SP"),
+
+    /**
+     * All read operations within a transaction access the database snapshot. Read only.
      * All the data reads are consistent. The snapshot is taken when the transaction begins,
      * meaning the transaction sees all changes committed before it began.
      */
-    SNAPSHOT("SP");
+    SNAPSHOT_READ_ONLY("SP");
+
+    // TODO(nvamelichev): Add support for SNAPSHOT_RW
 
     @Getter
     private final String txIdSuffix;
@@ -68,4 +82,16 @@ public boolean isReadOnly() {
     public boolean isReadWrite() {
         return this == SERIALIZABLE_READ_WRITE;
     }
+
+    /**
+     * Indicates whether the transaction offers <em>snapshot isolation</em>; YDB offers both read-only and read-write
+     * snapshot isolation.
+     *
+     * @return {@code true} if the transaction offers snapshot isolation; {@code false} otherwise
+     * @see #isReadOnly()
+     * @see #isReadWrite()
+     */
+    public boolean isSnapshot() {
+        return this == SNAPSHOT_READ_ONLY || this == SNAPSHOT;
+    }
 }

repository/src/main/java/tech/ydb/yoj/repository/db/TxManager.java

@@ -196,8 +196,7 @@ default TxManager noQueryTracing() {
 
     /**
      * Performs the specified action inside a transaction. The action must be idempotent, because it might be executed
-     * multiple times in case of {@link OptimisticLockException transaction lock
-     * invalidation}.
+     * multiple times in case of {@link OptimisticLockException transaction lock invalidation}.
      *
      * @param supplier action to perform
      * @return action result
@@ -206,8 +205,7 @@ default TxManager noQueryTracing() {
 
     /**
      * Performs the specified action inside a transaction. The action must be idempotent, because it might be executed
-     * multiple times in case of {@link OptimisticLockException transaction lock
-     * invalidation}.
+     * multiple times in case of {@link OptimisticLockException transaction lock invalidation}.
      *
      * @param runnable action to perform
      */
@@ -216,11 +214,12 @@ default TxManager noQueryTracing() {
     /**
      * Start a transaction-like session of read-only statements. Each statement will be executed <em>separately</em>,
      * with the specified isolation level (online consistent read-only, by default).
-     * <p>YDB doesn't currently support multi-statement read-only transactions. If you perform more than one read, be
-     * ready to handle potential inconsistencies between the reads.
+     * <p>YDB currently supports multi-statement read-only transactions only on {@link IsolationLevel#SNAPSHOT_READ_ONLY
+     * snapshot read-only isolation level}. If you perform more than one read statement on any other read-only isolation
+     * level, you must be ready to handle potential inconsistencies between the reads.
      * <p>You can also use {@code readOnly().run(() -> [table].readTable(...));} to efficiently read data from the table
      * without interfering with OLTP transactions. In this case, data consistency is similar to snapshot isolation. If
-     * perform more than one {@code readTable()}, be ready to handle potential inconsistencies between the reads.
+     * perform more than one {@code readTable()}, you must be ready to handle potential inconsistencies between the reads.
      */
     ReadonlyBuilder readOnly();
 

repository/src/main/java/tech/ydb/yoj/repository/db/TxOptions.java

@@ -76,6 +76,10 @@ public boolean isScan() {
         return scanOptions != null;
     }
 
+    public boolean isSnapshot() {
+        return isolationLevel.isSnapshot();
+    }
+
     public TimeoutOptions minTimeoutOptions(Duration timeoutFromExternalCtx) {
         if (timeoutFromExternalCtx == null && timeoutOptions == null) {
             return TimeoutOptions.DEFAULT;
@@ -109,7 +113,7 @@ public static class TimeoutOptions {
         Duration timeout;
 
         /**
-         * Calculates <b>canceAfter</b> parameter for ydb sdk, which must be 50-100ms less than a transport timeout.
+         * Calculates <b>canceAfter</b> parameter for YDB SDK, which must be 50-100ms less than a transport timeout.
          * The bigger the transport timeout, the bigger the difference.
          */
         public Duration getCancelAfter() {