Transaction Management

From BaseX Documentation

(Redirected from Transactions)
Jump to: navigation, 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 is some more information about the transaction management.


[edit] Introduction

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.

Please note that:

[edit] XQuery Update

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.

[edit] Concurrency Control

BaseX provides support for multiple read and single write operations (using preclaiming and starvation-free two phase locking). This means that:

[edit] XQuery Locks

By default, access to external resources (files on hard disk, HTTP requests, ...) is not controlled by the transaction monitor of BaseX. You can use custom XQuery locks to do so:

[edit] Options, Pragmas, Annotations

Introduced with Version 9.1: locks via pragmas and function annotations.

In the following module, lock annotations are used to prevent concurrent write operations on the same file:

module namespace config = 'config';

declare %basex:read-lock('CONFIG') function config:read() {

declare %basex:write-lock('CONFIG') function config:write($data) {
  file:write-text('config.txt', $data)

Some explanations:

Local locks can also be declared via pragmas:

(# basex:write-lock CONFIG #) {
  file:write('config.xml', <config/>)

Locks for the functions of a module can be assigned via option declarations:

declare option basex:write-lock 'CONFIG';
file:write('config.xml', <config/>)

Before Version 9.1, locks were declared in the query namespace.

[edit] Java Modules

Locks can also be acquired on Java functions which are imported and invoked from an XQuery expression. It is advisable to explicitly lock Java code whenever it performs sensitive read and write operations.

[edit] Limitations

[edit] Commands

Database locking works with all commands unless the glob syntax is used, such as in the following command call:

[edit] XQuery

Deciding which databases will be accessed by a complex XQuery expression is a non-trivial task. Database detection works for the following types of queries:

All databases will be locked by queries of the following kind:

You can consult the query info output (which you find in the Info View of the GUI or which you can turn on by setting QUERYINFO to true) to find out which databases have been locked by a query.

[edit] File-System Locks

[edit] Update Operations

During 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 will not be deleted. In this case, the database cannot be opened anymore, 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.

[edit] Database Locks

To avoid database corruptions that are caused by accidental write operations from 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, and if no exclusive lock can be acquired, it will be rejected with the message "Database ... is currently opened by another process.".

Please note that you cannot 100% rely on this mechanism, as it is not possible to synchronize operations across different JVMs. You will be safe when using the client/server or HTTP architecture.

[edit] Changelog

Version 9.1
Version 8.6
Version 7.8
Version 7.6
Version 7.2.1
Version 7.2
Version 7.1
Personal tools