arangodb · goedderz · Aug 11, 2025 · Aug 8, 2025 · Aug 8, 2025 · Aug 8, 2025
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,6 +1,9 @@
 devel
 -----
 
+* Deprecate rocksdb.transaction-lock-timeout option since we would
+  internally change this to a different value.
+
 * Rebuilt included rclone v1.65.2 with go1.23.12 and non-vulnerable
   dependencies.
 

diff --git a/arangod/RestHandler/RestDocumentHandler.cpp b/arangod/RestHandler/RestDocumentHandler.cpp
@@ -238,7 +238,7 @@ async<void> RestDocumentHandler::insertDocument() {
 
   bool const isMultiple = body.isArray();
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = !isMultiple;  // for now we only enable this for
+  trxOpts.avoidSnapshot = !isMultiple;  // for now we only enable this for
                                         // single document operations
 
   auto trx = co_await createTransaction(
@@ -588,7 +588,7 @@ async<void> RestDocumentHandler::modifyDocument(bool isPatch) {
 
   bool const isMultiple = body.isArray();
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = !isMultiple;  // for now we only enable this for
+  trxOpts.avoidSnapshot = !isMultiple;  // for now we only enable this for
                                         // single document operations
 
   // find collection given by name or identifier
@@ -748,7 +748,7 @@ async<void> RestDocumentHandler::removeDocument() {
 
   bool const isMultiple = search.isArray();
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = !isMultiple;  // for now we only enable this for
+  trxOpts.avoidSnapshot = !isMultiple;  // for now we only enable this for
                                         // single document operations
 
   auto trx = co_await createTransaction(

diff --git a/arangod/RocksDBEngine/Methods/RocksDBTrxBaseMethods.cpp b/arangod/RocksDBEngine/Methods/RocksDBTrxBaseMethods.cpp
@@ -105,7 +105,7 @@ Result RocksDBTrxBaseMethods::beginTransaction() {
   TRI_ASSERT(_rocksTransaction != nullptr);
   TRI_ASSERT(_rocksTransaction->GetSnapshot() == nullptr);
 
-  if (!_state->options().delaySnapshot) {
+  if (!_state->options().avoidSnapshot) {
     // In some cases we delay acquiring the snapshot so we can lock the key(s)
     // _before_ we acquire the snapshot to prevent write-write conflicts. In all
     // other cases we acquire the snapshot right now to be consistent with the
@@ -197,7 +197,7 @@ rocksdb::Status RocksDBTrxBaseMethods::Get(rocksdb::ColumnFamilyHandle* cf,
                                            ReadOwnWrites readOwnWrites) {
   TRI_ASSERT(cf != nullptr);
   rocksdb::ReadOptions const& ro = _readOptions;
-  TRI_ASSERT(ro.snapshot != nullptr || _state->options().delaySnapshot);
+  TRI_ASSERT(ro.snapshot != nullptr || _state->options().avoidSnapshot);
   if (readOwnWrites == ReadOwnWrites::yes) {
     return _rocksTransaction->Get(ro, cf, key, val);
   }
@@ -210,7 +210,7 @@ rocksdb::Status RocksDBTrxBaseMethods::GetForUpdate(
   TRI_ASSERT(cf != nullptr);
   TRI_ASSERT(_rocksTransaction);
   rocksdb::ReadOptions const& ro = _readOptions;
-  TRI_ASSERT(ro.snapshot != nullptr || _state->options().delaySnapshot);
+  TRI_ASSERT(ro.snapshot != nullptr || _state->options().avoidSnapshot);
   rocksdb::Status s = _rocksTransaction->GetForUpdate(ro, cf, key, val);
   if (s.ok()) {
     _memoryTracker.increaseMemoryUsage(
@@ -383,13 +383,13 @@ void RocksDBTrxBaseMethods::createTransaction() {
   if (_state->hasHint(transaction::Hints::Hint::IS_FOLLOWER_TRX)) {
     // write operations for the same keys on followers should normally be
     // serialized by the key locks held on the leaders. so we don't expect
-    // to run into lock conflicts on followers. however, the lock_timeout
-    // set here also includes locking the striped mutex for _all_ key locks,
-    // which may be contended under load. to avoid timeouts caused by
-    // waiting for the contented striped mutex, increase it to a higher
-    // value on followers that makes this situation unlikely.
+    // to run into lock conflicts on followers. the lock_timeout doesn't do
+    // much here since the RocksDB does not differentiate between
+    // lock timeout on striped_mutex for PointLockManager and on single
+    // documents, this timeout is ignored unless it is set to 0, then we
+    // try_lock otherwise we just lock.
     trxOpts.lock_timeout = 3000;
-  } else if (_state->options().delaySnapshot) {
+  } else if (_state->options().avoidSnapshot) {
     // for single operations we delay acquiring the snapshot so we can lock
     // the key _before_ we acquire the snapshot to prevent write-write
     // conflicts. in this case we obviously also want to use a higher lock
@@ -399,6 +399,10 @@ void RocksDBTrxBaseMethods::createTransaction() {
   } else {
     // when trying to lock the same keys, we want to return quickly and not
     // spend the default 1000ms before giving up
+    // Setting lock_timeout to 0 is not an option because then RocksDB uses
+    // try_lock on the striped mutex, and if it cannot acquire the lock it
+    // fails which can lead to spurious failures without having
+    // conflicting transactions.
     trxOpts.lock_timeout = 1;
   }
 

diff --git a/arangod/RocksDBEngine/RocksDBOptionFeature.cpp b/arangod/RocksDBEngine/RocksDBOptionFeature.cpp
@@ -408,18 +408,21 @@ values to reduce a potential contention in the lock manager.
 The option defaults to the number of available cores, but is increased to a
 value of `16` if the number of cores is lower.)");
 
-  options->addOption(
-      "--rocksdb.transaction-lock-timeout",
-      "If positive, specifies the wait timeout in milliseconds when "
-      " a transaction attempts to lock a document. A negative value "
-      "is not recommended as it can lead to deadlocks (0 = no waiting, < 0 no "
-      "timeout)",
-      new Int64Parameter(&_transactionLockTimeout),
-      arangodb::options::makeFlags(
-          arangodb::options::Flags::DefaultNoComponents,
-          arangodb::options::Flags::OnAgent,
-          arangodb::options::Flags::OnDBServer,
-          arangodb::options::Flags::OnSingle));
+  options
+      ->addOption(
+          "--rocksdb.transaction-lock-timeout",
+          "If positive, specifies the wait timeout in milliseconds when "
+          " a transaction attempts to lock a document. A negative value "
+          "is not recommended as it can lead to deadlocks (0 = no waiting, < 0 "
+          "no timeout). This is deprecated since we internally control the "
+          "lock timeout for different cases.",
+          new Int64Parameter(&_transactionLockTimeout),
+          arangodb::options::makeFlags(
+              arangodb::options::Flags::DefaultNoComponents,
+              arangodb::options::Flags::OnAgent,
+              arangodb::options::Flags::OnDBServer,
+              arangodb::options::Flags::OnSingle))
+      .setDeprecatedIn(31206);
 
   options
       ->addOption(

diff --git a/arangod/Transaction/Options.h b/arangod/Transaction/Options.h
@@ -108,10 +108,9 @@ struct Options {
   bool requiresReplication = true;
 
   /// @brief If set to true, the transaction is started without acquiring a
-  /// snapshot. The snapshot can be acquired at a later point by calling
-  /// `ensureSnapshot`. This allows us to lock the used keys before the
+  /// snapshot. This allows us to lock the used keys before the
   /// snapshot is acquired in order to avoid write-write conflict.
-  bool delaySnapshot = false;
+  bool avoidSnapshot = false;
 
   /// @brief if set to true, skips the fast, unordered lock round and always
   /// uses the sequential, ordered lock round.

diff --git a/arangod/V8Server/v8-collection.cpp b/arangod/V8Server/v8-collection.cpp
@@ -744,7 +744,7 @@ static void RemoveVocbaseCol(v8::FunctionCallbackInfo<v8::Value> const& args) {
 
   bool payloadIsArray = args[0]->IsArray();
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = !payloadIsArray;  // for now we only enable this for
+  trxOpts.avoidSnapshot = !payloadIsArray;  // for now we only enable this for
                                             // single document operations
 
   VPackSlice toRemove = searchBuilder.slice();
@@ -845,7 +845,7 @@ static void RemoveVocbase(v8::FunctionCallbackInfo<v8::Value> const& args) {
   TRI_ASSERT(toRemove.isObject());
 
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = true;
+  trxOpts.avoidSnapshot = true;
 
   SingleCollectionTransaction trx(
       std::shared_ptr<transaction::Context>(
@@ -1534,7 +1534,7 @@ static void ModifyVocbaseCol(TRI_voc_document_operation_e operation,
 
   bool payloadIsArray = args[0]->IsArray();
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = !payloadIsArray;  // for now we only enable this for
+  trxOpts.avoidSnapshot = !payloadIsArray;  // for now we only enable this for
                                             // single document operations
 
   // Now start the transaction:
@@ -1656,7 +1656,7 @@ static void ModifyVocbase(TRI_voc_document_operation_e operation,
   }
 
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = true;
+  trxOpts.avoidSnapshot = true;
 
   SingleCollectionTransaction trx(
       std::shared_ptr<transaction::Context>(
@@ -1954,7 +1954,7 @@ static void InsertVocbaseCol(v8::Isolate* isolate,
   }
 
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = !payloadIsArray;  // for now we only enable this for
+  trxOpts.avoidSnapshot = !payloadIsArray;  // for now we only enable this for
                                             // single document operations
 
   auto origin = transaction::OperationOriginREST{"inserting document(s)"};

diff --git a/tests/sepp/Workloads/WriteWriteConflict.cpp b/tests/sepp/Workloads/WriteWriteConflict.cpp
@@ -88,7 +88,7 @@ void WriteWriteConflict::Thread::run() {
   }
 
   transaction::Options trxOpts;
-  trxOpts.delaySnapshot = _options.delaySnapshot;
+  trxOpts.avoidSnapshot = _options.avoidSnapshot;
 
   for (;;) {
     SingleCollectionTransaction trx(

diff --git a/tests/sepp/Workloads/WriteWriteConflict.h b/tests/sepp/Workloads/WriteWriteConflict.h
@@ -71,14 +71,14 @@ struct WriteWriteConflict::Options {
   struct Thread {
     std::string collection;
     OperationType operation;
-    bool delaySnapshot;
+    bool avoidSnapshot;
 
     template<class Inspector>
     friend inline auto inspect(Inspector& f, Thread& o) {
       return f.object(o).fields(
           f.field("collection", o.collection),
           f.field("operation", o.operation),
-          f.field("delaySnapshot", o.delaySnapshot).fallback(true));
+          f.field("avoidSnapshot", o.avoidSnapshot).fallback(true));
     }
   };