Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
NotePlease note that:An unexpected abort of the server during a transaction, caused by a hardwarefailure or power cut, may lead to an inconsistent database state if a transaction was active at the shutdown time. So we advise to usethe [[Commands#CREATE BACKUP|BACKUP]] command to backup your database regularly. If the worst case occurs, you can try the [[Commands#INSPECT|INSPECT]] command to check if your database has obvious inconsistencies, and [[Commands#RESTORE|RESTORE]] to restore a previous version of the database.
==Transaction Monitor==* Read transactions are executed in parallel.* If an updating transaction comes in, it will be queued and executed after all previous read transaction have been executed.* Subsequent operations (read or write) will be queued until the updating transaction has completed.
The Each database has its own queue: An update on database A will not block operations on database B. This is under the premise that it can be statically determined, i.e., before the transaction monitor ensures that just one writing is evaluated, which databases will be accessed by a transaction or an arbitrary amount (see [[#Limitations|below]]). The number of reading maximum parallel transactions ''per database'' are active at can be adjusted with the same time[[Options#PARALLEL|PARALLEL]] option.
Deadlocks are prevented by using preclaiming two phase lockingWith {{Version|8. Execution is starvation-free as lock acquisition is queued per database. Due to the specifics of XQuery Update6}}, 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.locking has been improved:
Locks are not synchronized between multiple BaseX instances* Jobs without database access will never be locked. We generally recommend working Globally locking jobs can now be executed in parallel with non-locking jobs.* A {{Option|FAIRLOCK}} option has been added: By default, read transactions will now be favored, and transactions that access no databases can be evaluated even if the client/server architecture if concurrent write operations are to be performedtransactions limit has been reached.
Since {{Version|7.8}}, locks Locks can also be specified for acquired on [[Java Bindings#Java functionsLocking|Java functions]] that which are called imported and invoked from an XQuery expression. It is advisable to explicitly lock Java code whenever it performs sensitive read and write operations.
As XQuery is a very powerful language, deciding Deciding which databases will be accessed by a query complex XQuery expression is a non-trivialtask. Optimization is work in progress.The current identification Database detection works for the following types of which databases to lock is limited to queries that access the currently opened database, XQuery functions that explicitly specify a database, and expressions that address no database at all. Some examples on database-locking enabled queries, all of these can be executed in parallel:
Some examples on All databases will be locked by queries that are not supported by database-locking yet: * <code>let $db := 'factbook' return doc($db)</code>, will read-lockof the following kind: referencing database names isn’t supported yet* {{Code|for $db in ('factbook') return doc($db)}}, will read-lock globally* {{Code|doc(doc('test')/reference/text())}}, will read-lock globally* <code>let $db := 'test' return insert nodes <test/> into doc($db)</code>, will write-lock globally
A list of all locked databases is output if <code>[[Options#QUERYINFO* {{Code|QUERYINFO]]</code> is set to for $db in ('db1', 'db2') return doc($db)}}* {{Code|truedoc(doc('test')/reference/text())}}. * <!-- and in the GUI's [[GUI#Visualizations|Info View]] --code> If you think that too much is locked, please give us a note on our [httplet $db := 'test' return insert nodes <test/> into doc($db)</basex.org/open-source/ mailing list] with some example code.>
===You can consult the query info output (which you find in the [[GUI=== Database locking is currently disabled if #Visualizations|Info View]] of the BaseX GUI is used. ==How to disable== In order to disable traditional process locking, the option or which you can turn on by setting <code>[[Options#GLOBALLOCKQUERYINFO|GLOBALLOCKQUERYINFO]]</code> can be set to {{Code|falsetrue}}. This can e.g. be done by editing your {{Code|.basex}} file (see [[Options]] for more details). To enable it again, set it to {{Code|true}}find out which databases have been locked by a query.
As the standalone versions of BaseX (command-linePlease note that you cannot 100% rely on this mechanism, GUI) cannot as it is not possible to synchronize operations across different JVMs. You will be synchronized with other BaseX instances, we generally recommend working with safe when using the client/server or HTTP architecture if concurrent write operations are to be performed.
→Concurrency Control
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 is some moreinformations information about the transaction management.
=TransactionIntroduction=
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.
* Locks ''cannot be synchronized'' across BaseX instances that run in different JVMs. If concurrent write operations are to be performed, we generally recommend working with the client/server or the HTTP architecture .* An ''unexpected abort'' of the server during a transaction, caused by a hardware failure or power cut, may lead to an inconsistent database state if a transaction was active at shutdown time. So it is advisable to use the [[Commands#CREATE BACKUP|BACKUP]] command to regularly backup your database. If the worst case occurs, you can try the [[Commands#INSPECT|INSPECT]] command to check if your database has obvious inconsistencies, and use [[Commands#RESTORE|RESTORE]] to restore the last backed up version of the database. ==XQuery Update Transactions==
Many update operations are triggered by [[Update|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 provides support for multiple read and single write operations (using preclaiming and starvation-free two phase 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 [[Options#PARALLEL|PARALLEL]] option).This means that:
==External Side Effects==
Access to external resources (files on hard disk, HTTP requests, ...) is not controlled by BaseX' the transaction monitor of BaseX unless specified by the user.
===XQuery Locking Options===
Custom locks can be acquired by setting the BaseX-specific XQuery options {{Code|query:read-lock}} and {{Code|query:write-lock}}. It accepts arbitrary strings, for locking. The Multiple option declarations may occur in the prolog of a query, but multiple values can also be set multiple times to acquire multiple locks, or use separated with commas in a colon as separator between themsingle declaration. These locks are in another namespace than the database names, locking ": the lock value {{Code|factbook" using the options does }} will not lock the a database named factbook.
These options option declarations will put read locks on ''foo'', ''bar'' and ''batz'' and a write lock on ''quix''.:
<pre class="brush:xquery">declare option query:read-lock "foo,bar";
declare option query:read-lock "batz";
declare option query:write-lock "quix";</pre>
===Java Modules===
==Limitations==
===Commands===
Database locking works with all commands unless no the glob syntax is used, such as in the following command call:
* {{Code|DROP DB new*}}: drop all databases starting with "new"
===XQuery===
* {{Code|//item}}, read-locking of the database opened by a client
* {{Code|delete nodes doc('test')//*[string-length(local-name(.)) > 5]}}, write-locking of "test"
=File-System Locks=
==Update Operations==
During the term of a database update, a locking file {{Code|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 will 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 that are caused by accidental write operations running in from different JVMs, a shared lock is requested on the database table file ({{Code|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." if no exclusive lock can be acquired.
=Changelog=
;Version 8.6
* Updated: New {{Option|FAIRLOCK}} option, improved detection of lock patterns.
;Version 7.8
* Added: Locks can also be acquired on [[Java Bindings#Locking|Java functions]].
;Version 7.6
* Added: database locking introduced, replacing process locking.
;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 [[Category:Server]][[Category:Internals]].
