Changes

* Locks are not ''cannot be synchronized between '' 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.

BaseX provides support for multiple read and single write operations (using preclaiming and starvation-free two phase locking). This means that 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 will also be queued until the updating transaction has completed.:

* 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.* Jobs without database access will never be locked. Globally locking jobs can now be executed in parallel with non-locking jobs.* 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 is evaluated) , which databases will be accessed by a transaction:(see [[#Limitations|below]]).* The number of maximum parallel transactions can be adjusted with the {{Option|PARALLEL}} option.* By default, read transactions are favored, and transactions that access no databases can be evaluated even if the transactions limit has been reached. This behavior can be changed via the {{Option|FAIRLOCK}} option.

<pre class="brush=Limitations== ===Commands=== Database locking works with all commands unless the glob syntax is used, such as in the following command call:java">OPEN db; ADD factbook.xml; CLOSEXQUERY insert node <a/> into db* {{Code|DROP DB new*}}:open('db')/*drop all databases starting with "new" </pre>===XQuery===

In the following example, all Deciding which databases will be blocked, because accessed by a complex XQuery expression is a non-trivial task. Database detection works for the name following types of the second database, which will be opened in the query, will only be known after having opened the first databasequeries:

<pre class=* {{Code|//item}}, read-locking of the database opened by a client* {{Code|doc('factbook')}}, read-locking of "brush:xqueryfactbook">let $db1 := db:open* {{Code|collection('catalogdb/path/to/docs')//}}, read-locking of "db-name[@id = '123']"let $db2 * {{Code|fn:= sum(1 to 100)}}, locking nothing at all* {{Code|delete nodes db:open($db'test')return delete node $db2//text*[string-length(local-name(.))</pre>5]}}, write-locking of "test"

The number A global lock will be assigned if the name of maximum parallel transactions can be adjusted with the [[Options#PARALLEL|PARALLEL]] option.database is not a static string:

* {{Code|for $db in ('db1', 'db2') return db:open($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db :==External Side Effects=='test' return insert nodes <test/> into db:open($db)</code>

Access The functions [[Databases#XML Documents|fn:doc]] and [[Databases#XML Documents|fn:collection]] can also be used to external resources (files on hard diskaddress that are not stored in a database. However, this may lead to unwanted locks, HTTP requestsand you have two options to reduce the number of locks: No database lookups will take place if {{Option|WITHDB}} option is disabled, ...) or if {{Function|Fetch|fetch:xml}} is not controlled by the transaction monitor used instead of BaseX unless specified by the user[[Databases#XML Documents|fn:doc]].

Custom locks can be acquired by setting the BaseX-specific =XQuery options {{Code|query:read-lock}} and {{Code|query:write-lock}}. Multiple option declarations may occur in the prolog of a query, but multiple values can also be separated with commas in a single declaration. These locks are in another namespace than the database names: the lock value {{Code|factbook}} will not lock a database named factbook.Locks=

These {{Mark|Updated with Version 9.4:}} Single lock option declarations will put read locks on ''foo'', ''bar'' for reads and ''batz'' and a write lock on ''quix'':writes.

<pre class="brush:xquery">declare option query:read-lock "fooBy default, access to external resources (files on hard disk, HTTP requests, ...) is not controlled by the transaction monitor of BaseX. Custom locks can be assigned via annotations,bar";declare option query:read-lock "batz";declare option querypragmas or options:write-lock "quix";</pre>

Locks can also be acquired on [[Java Bindings#Locking|Java functions]] which ==Annotations== In the following module, lock annotations are imported and invoked from an XQuery expression. It is advisable used to explicitly lock Java code whenever it performs sensitive read and prevent concurrent write operations.on the same file: <syntaxhighlight lang="xquery">module namespace config = 'config';

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

* If a query calls the <code>config:read</code> function, a read lock will be acquired for the user-defined {{Code|DROP DB new*CONFIG}}lock string before query evaluation.* If <code>config:write</code> is called by a query, a write lock will be applied.* If another query calls <code>config: drop all databases starting with "new"write</code>, it will be queued until the first query is evaluated.

===XQuery=Pragmas==

As XQuery is a very powerful language, deciding which databases will Locks can also be accessed by a query is non-trivial. Optimization is work in progress.The current identification 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.declared via pragmas:

Some examples on database-locking enabled queries<syntaxhighlight lang="xquery">update:output((# basex:lock CONFIG #) { file:write('config.xml', all of these can be executed in parallel:<config/>)})</syntaxhighlight>

* {{Code|//item}}, read-locking of The write locks is enforced via the database opened by a client* {{Code|doc('factbook')}}, read-locking of "factbook"* {{CodeUpdate|collection('db/path/to/docs')}}, read-locking of "db"* {{Code|fnupdate:sum(1 to 100)output}}, locking nothing at all* {{Code|delete nodes doc('test')//*[string-length(local-name(.)) > 5]}}, write-locking of "test"

* <code>let $db := 'factbook' return doc($db)</code>, will read-lock: referencing database names isn’t supported yet* {{Code|Locks for $db in ('factbook') return doc($db)}}, will read-lock globally* {{Code|doc(doc('test')/reference/text())}}, will read-lock globally* <code>let $db the functions of a module can also be assigned via option declarations:= 'test' return insert nodes <test/> into doc($db)</code>, will write-lock globally

A list of all locked databases is output if <codesyntaxhighlight lang="xquery">[[Options#QUERYINFO|QUERYINFO]]</code> is set to {{Code|true}}. <!-- and in the GUIdeclare option basex:lock 'CONFIG's [[GUI#Visualizations|Info View]] --> If you think that too much is locked, please give us a note on our [http://basex.org/open-source/ mailing list] with some example code.;

Database locking Once again, a write lock is currently disabled if the BaseX GUI is usedenforced.

==Process LockingJava Modules==

In order to enable locking Locks can also be acquired on global (process) level, the option <code>[[OptionsJava Bindings#GLOBALLOCK|GLOBALLOCK]]</code> can be set to {{Code|true}}. This can e.g. be done by editing your {{CodeLocking|.basex}} file (see [[OptionsJava functions]] for more details)which are imported and invoked from an XQuery expression. If process locking It is active, a process that advisable to explicitly lock Java code whenever it performs sensitive read and write operations will queue all other 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.

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.

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.