Transaction Management

From BaseX Documentation
Revision as of 23:26, 13 January 2013 by Jens Erat (talk | contribs) (How to enable database locking.)
Jump to navigation Jump to search

This article is part of the Advanced User's Guide. The BaseX client-server architecture offers ACID safe transactions, with multiple readers and writers. Here are some more informations about the transaction management.


In a nutshell, a transaction is equal to a command or query. So each command or query sent to the server becomes a transaction.

Incoming requests are parsed and checked for errors on the server. If the command or query is not correct, the request will not be executed, and the user will receive an error message. Otherwise the request becomes a transaction and gets into the transaction monitor.

Note: An unexpected abort of the server during a transaction, caused by a hardware failure or power cut, will probably lead to an inconsistent database state if a transaction was active at the shutdown time. So we advise to use the BACKUP command to backup your database regularly. If the worst case occurs, you can try the INSPECT command to check if your database has obvious inconsistencies, and RESTORE to restore a previous version of the database.

Update Transactions

Many update operations are triggered by XQuery Update expressions. When executing an updating query, all update operations of the query are stored in a pending update list. They will be executed all at once, so the database is updated atomically. If any of the update sub-operations is erroneous, the overall transaction will be aborted.

Concurrency Control

BaseX 7.5.1 introduces locking on database level. Writing transactions do not necessarily block all other transactions any more. The number of parallel transactions can be limited by setting the PARALLEL option.

Transaction Monitor

The transaction monitor ensures that just one writing transaction or an arbitrary amount of reading transactions per database are active at the same time.

Deadlocks are prevented by using preclaiming two phase locking. Execution is starvation-free as lock aquiration is queued per database. Because of XQuery Update specifies all updates are written at the end of the query, locking is strict with the exception that databases for which BaseX recognizes it will not write to are downgraded to read locks.

Locks are not synchronized between multiple BaseX instances. We generally recommend working with the client/server architecture if concurrent write operations are to be performed.

How to enable

There is a hidden option DBLOCKING which is set to false (disabling database locking) by default. You can enable it using the latest developer release by editing your .basex file and setting it to true. For disabling it again, set it to false.


Database currently is disabled if using the BaseX Gui.

As XQuery is a very powerful language, deciding which databases will be accessed by a query is non-trivial. Optimization is work in progress. Databases locked by a query are listed in the GUI's Info View and on the command line client if QUERYINFO is set. If you think too much is locked, please give us a note on our mailing list with some example code.

Currently identifying which databases to lock is limited to database calls directly addressing databases without references (or none at all).

Some examples on database-locking enabled queries:

  • doc('factbook'), read-locking "factbook"
  • collection('db/path/to/docs'), read-locking "db"
  • fn:sum(1 to 100), locking nothing at all
  • delete nodes doc('test')//*[string-length(local-name(.)) > 5], write-locking "test"
  • CREATE DB newdb, write-locking "newdb"

All of these queries can be executed in parallel.

Some examples on queries not supported by database-locking yet:

  • let $db := 'factbook' return doc($db), will read lock globally: referencing database names isn't supported yet
  • for $db in ('factbook') return doc($db), will read lock globally: ditto
  • doc(doc('test')/reference/text()), will read lock globally: ditto
  • let $db := 'test' return insert nodes <test/> into doc($db), will write lock globally: ditto

Before BaseX 7.5.1

Update Operations

During the term of a database update, a locking file upd.basex will reside in that database directory. If the update fails for some unexpected reason, or if the process is killed ungracefully, this file may not be deleted. In this case, the database cannot be opened anymore using the default commands, and the message "Database ... is being updated, or update was not completed" will be shown instead. If the locking file is manually removed, you may be able to reopen the database, but you should be aware that database may have got corrupt due to the interrupted update process, and you should revert to the most recent database backup.

Database Locks

To avoid database corruptions caused by write operations running in different JVMs, a shared lock is requested on the database table file (tbl.basex) whenever a database is opened. If an update operation is triggered, it will be rejected with the message "Database ... is opened by another process." if no exclusive lock can be acquired.

As the standalone versions of BaseX (command-line, GUI) cannot be synchronized with other BaseX instances, we generally recommend working with the client/server architecture if concurrent write operations are to be performed.


Version 7.5.1
  • Added: database locking introduced
Version 7.2.1
  • Updated: pin files replaced with shared/exclusive filesystem locking
Version 7.2
  • Added: pin files to mark open databases
Version 7.1
  • Added: update lock files