Transaction Management

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

Transaction

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 restore the database with the RESTORE command.

Update Transactions

Update transactions are mainly update queries. When executing a XQuery Update 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

The concurrency control checks for each transaction, which will perform a read or write operation on the database, the status of the lock object and decides whether the isolation is guaranteed for that transaction or not. If the isolation can be guaranteed the transaction will be started immediately. Otherwise, the transaction enters a waiting queue and waits till the transaction monitor validates and starts the transaction. The transaction monitor starts either the next writing transaction or the next group of reading transactions (if there are any on the queue).

Transaction Monitor

The transaction monitor ensures that just one writing transaction is active at the same time. This seems to be an odd mechanism, but it is needed since the complexity of updates increased and it is possible now to access multiple databases in one XQuery Update query.
To avoid starvation of any transaction and wrong execution orders the waiting queue works with the FIFO principle ('First-In First-Out'), which states that the first process that arrives at the server will be the first one that will be executed. The FIFO principle cannot be adhered in a group of reading transactions, as they run in different threads and thus can overtake each other.
The use of the monitor also prevents the system from deadlocks, because the critical resource is only assigned to one writing transaction resp. a group of reading transactions.

Updates

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 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.

Pins

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

To avoid database corruptions caused by unmanaged concurrent write operations, a process-specific pin...basex file will be created in a database directory when a database is opened. When an update operation is triggered, it will be rejected with the message "Database ... is opened by another process." if other pin files are found in the directory.

The same message may appear whenever an unused pin file remains after a client has been ungracefully killed or shut down. In this case, you may manually remove the pin files.