Changes

* Locks ''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 It is advisable to use the [[Commands#{{Command|CREATE BACKUP|BACKUP]] }} command to regularly backup back up your database. If the worst case occurs, you can try the [[Commands#INSPECT{{Command|INSPECT]] }} command to check if your database has obvious inconsistencies, and use [[Commands#RESTORE{{Command|RESTORE]] }} to restore the last backed up version of the database.

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 [[Options#PARALLEL|PARALLEL]] option.==

==External Side Effects=Commands===

Access to external resources (files on hard disk, HTTP requests, All commands come with a detector for local locks...) Global locking is not controlled by applied if the transaction monitor of BaseX unless specified by the user.glob syntax is used:

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

These option declarations will put read locks on ''foo''Since BaseX 10, ''bar'' and ''batz'' and a write the [[BaseX 10#Compilation|lock on ''quix'':detection has been fundamentally improved]], by splitting compilation into multiple steps.

Local locks can be applied if it is possible after compile time to associate all database operations with static databases names: {| class="wikitable"|- valign="top"! Query! Description|- valign="top"| <code>//item</code>| Read lock of the currently opened database|- valign="top"| <code>doc('factbook')</code>| Read lock of the {{Code|factbook}} database|- valign="top"| <code>collection('documents/path/to/docs')<pre class/code>| Read lock of the {{Code|documents}} database|- valign="top"| <code>delete nodes db:get('test')//*[@type = 'misc']</code>| Write lock of the {{Code|test}} database|- valign="brushtop"| <code>declare variables $db external;<br/>db:xqueryget($db)</code>| Read lock of the database externally bound to {{Code|$db}}.|- valign="top"| <code>for $db in ('db1', 'db2')<br/>return db:get($db)</code>declare option | Read lock of {{Code|db1}} and {{Code|db2}}, as the queryis [[XQuery Optimizations#Loop Unrolling|unrolled at compile time]].|- valign="top"| <code>let $db :read= 'test'<br/>return insert nodes <test/> into db:get($db)</code>| Read lock of {{Code|test}}, as the [[XQuery Optimizations#Variable_Inlining|variable is inlined]] at compile time.|-valign="top"| <code>sum(1 to 100)</code>| No lock required|- valign="foo,bartop"| <code>declare variable $SIMULATE := true();<br/>if($SIMULATE) then <doc/> else db:get('doc')</code>declare option | No lock required, as the queryis simplified to {{Code|<doc/>}} at compile time.|} A global lock will be assigned if the static detection fails:read {| class="wikitable"|- valign="top"! Query! Description|-lock valign="batztop";declare option query| <code>db:writeget(doc('test')/reference/text())</code>| The name of the database to be opened will only be known at evaluation time.|-lock valign="quixtop";| <code>(1 to 100) ! db:get(concat('db', .))</precode>| The {{Option|UNROLLLIMIT}} can be increased to generate 100 {{Code|db:get}} function calls and corresponding locks.|} The functions {{Code|fn:doc}} and {{Code|fn:collection}} can be used for both accessing databases resources and fetching resources at the specified URI (see [[Databases#Access Resources|Access Resources]] for more details). There are two ways to reduce the number of locks: # Turn off the {{Option|WITHDB}} option to prevent the functions from accessing databases; or# use {{Function|Fetch|fetch:doc}} for fetching resources from URIs, and use {{Function|Database|db:get}} for accessing databases. You can consult the query info output (via the [[GUI#Visualizations|Info View]] of the GUI, via {{Code|-V}} on [[Command-Line]] or via turning on the {{Option|QUERYINFO}} option) to find out which databases are locked by a query, and if local locks or a global lock is applied. =XQuery Locks= By 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, pragmas or options: * A lock string may consist of a single key or multiple keys separated with commas.* Internal locks and XQuery locks can co-exist. No conflicts arise, even if a lock string equals the name of a database that is locked by the transaction manager.* The lock is transformed into a write lock by making the corresponding expression updating. ==Annotations== In the following module, lock annotations are used to prevent concurrent write operations on the same file:

<pre lang='xquery'>module namespace config ==Java Modules==='config';

Locks can also be acquired on [[Java Bindings#Locking|Java functions]] which are imported and invoked from an XQuery expression. It is advisable to explicitly declare %basex:lock Java code whenever it performs sensitive ('CONFIG') function config:read() as xs:string { file:read and write operations-text('config.txt')};

Database locking works with all commands unless * If a query calls a reading <code>basex:lock</code> function, a read lock will be acquired for the glob syntax user-defined {{Code|CONFIG}} lock string before query evaluation.* If an updating <code>basex:lock</code> is usedcalled by a query, such as in a write lock will be applied.* If another query calls a <code>basex:lock</code> function, it will be queued until the following command call:first query is evaluated.

Deciding which databases will be accessed by a complex XQuery expression is a non-trivial task<pre lang='xquery'>update:output((# basex:lock CONFIG #) { file:write('config. Database detection works for the following types of queries:xml', <config/>)})</pre>

* {{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|Locks for $db in ('db1', 'db2') return doc($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db the functions of a module can also be assigned via option declarations:= 'test' return insert nodes <test/> into doc($db)</code>

You can consult the query info output (which you find in the [[GUI#Visualizations|Info View]] of the GUI or which you can turn on by setting <codepre lang='xquery'>[[Options#QUERYINFO|QUERYINFO]]</code> to {{Code|true}}) to find out which databases have been locked by a query.declare option basex:lock 'CONFIG';

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.