Transactional file locking

Nextcloud’s Transactional File Locking mechanism locks files to avoid file corruption during normal operation. It performs these functions:

  • Operates at a higher level than the filesystem, so you don’t need to use a filesystem that supports locking

  • Locks parent directories so they cannot be renamed during any activity on files inside the directories

  • Releases locks after file transactions are interrupted, for example when a sync client loses the connection during an upload

  • Manages locking and releasing locks correctly on shared files during changes from multiple users

  • Manages locks correctly on external storage mounts

  • Manages encrypted files correctly

What Transactional File locking is not for: it will not prevent multiple users from editing the same document, or give notice that other users are working on the same document. Multiple users can open and edit a file at the same time and Transactional File locking does not prevent this. Rather, it prevents simultaneous file saving.

Transactional File locking will use the database locking backend by default. This places a significant load on your database. Setting memcache.locking relieves the database load and improves performance. Admins of Nextcloud servers with heavy workloads should install a memcache. (See Memory caching.)

To use a memcache with Transactional File Locking, you must install a key-value store server like Valkey or Redis. Two cache backends are available for it:

Using the Nextcloud KeyValueCache cache

The KeyValueCache cache is built on a library bundled with Nextcloud, so no PHP module needs to be installed — you only need a running Valkey or Redis compatible server. Enter a configuration in your config.php file like this example:

'memcache.locking' => '\OC\Memcache\KeyValueCache',
'memcache.kvstore' => [
     'server' => [
          'host' => 'localhost',
          'port' => 6379,
     ],
     'password' => '', // Optional, if not defined no password will be used.
],

See Redis / Valkey using the Nextcloud KeyValueCache for all available options, including Unix sockets, TLS, Sentinel and cluster setups.

Using the Redis cache with the phpredis PHP module

To use the Redis cache instead, you must install the Redis server and corresponding PHP module. After installing Redis you must enter a configuration in your config.php file like this example:

'memcache.locking' => '\OC\Memcache\Redis',
'redis' => array(
     'host' => 'localhost',
     'port' => 6379,
     'timeout' => 0.0,
     'password' => '', // Optional, if not defined no password will be used.
      ),

Note

For enhanced security it is recommended to configure your key-value store server to require a password. See http://redis.io/topics/security or https://valkey.io/topics/security/ for more information.

If you want to configure Redis to listen on an Unix socket (which is recommended if Redis is running on the same system as Nextcloud) use this example config.php configuration:

'memcache.locking' => '\OC\Memcache\Redis',
'redis' => array(
     'host' => '/run/redis/redis-server.sock',
     'port' => 0,
     'timeout' => 0.0,
      ),

See config.sample.php to see configuration examples for Redis, and for all supported memcaches.

Learn more about Redis at Redis. Memcached, the popular distributed memory caching system, is not suitable for the new file locking because it is not designed to store locks, and data can disappear from the cache at any time. Redis is a key-value store, and it guarantees that cached objects are available for as long as they are needed.