Changes

* 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 ==Limitations== ===Commands=== All commands come with a detector for local locks. Global locking is applied if the glob syntax is used: * {{Code|DROP DB new*}}: Drop all databases starting with the prefix string {{Code|new}}. ===XQuery=== Since BaseX 10, the [[BaseX 10#Compilation|lock 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 has its own queueoperations 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')</code>| Read lock of the {{Code|documents}} database|- valign="top"| <code>delete nodes db: An update on get('test')//*[@type = 'misc']</code>| Write lock of the {{Code|test}} database A will not block operations on |- valign="top"| <code>declare variables $db external;<br/>db:get($db)</code>| Read lock of the database Bexternally bound to {{Code|$db}}. This |- valign="top"| <code>for $db in ('db1', 'db2')<br/>return db:get($db)</code>| Read lock of {{Code|db1}} and {{Code|db2}}, as the query is under [[XQuery Optimizations#Loop Unrolling|unrolled at compile time]].|- valign="top"| <code>let $db := 'test'<br/>return insert nodes <test/> into db:get($db)</code>| Read lock of {{Code|test}}, as the premise that it can be statically determined, i.e[[XQuery Optimizations#Variable_Inlining|variable is inlined]] at compile time.|- valign="top"| <code>sum(1 to 100)</code>| No lock required|- valign="top"| <code>declare variable $SIMULATE := true();<br/>if($SIMULATE) then <doc/> else db:get('doc')</code>| No lock required, before as the transaction query is evaluatedsimplified to {{Code|<doc/>}} at compile time.|} A global lock will be assigned if the static detection fails: {| class="wikitable"|- valign="top"! Query! Description|- valign="top"| <code>db:get(doc('test')/reference/text()) which databases </code>| The name of the database to be opened will only be accessed by a transaction known at evaluation time.|- valign="top"| <code>(1 to 100) ! db:get(concat('db', .))</code>| 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#LimitationsAccess Resources|belowAccess Resources]]for more details). The There are two ways to reduce the number of maximum parallel transactions 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 be adjusted with consult the query info output (via the [[OptionsGUI#PARALLELVisualizations|Info View]] of the GUI, via {{Code|PARALLEL-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:

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 <pre lang='xquery'>module namespace than the database names: the lock value {{Code|factbook}} will not lock a database named factbook.config = 'config';

These option declarations will put read locks on ''foo'', ''bar'' and ''batz'' and a write declare %basex:lock on ('CONFIG'quix) function config:read() as xs:string { file:read-text('config.txt':)};

<pre class="brush:xquery">declare option query%updating %basex:read-lock "foo,bar";declare option query('CONFIG') function config:write($data as xs:read-lock "batz";string) {declare option query file:write-lock "quix"text('config.txt', $data)};

Locks can also * If a query calls a reading <code>basex:lock</code> function, a read lock will be acquired on [[Java Bindings#Lockingfor the user-defined {{Code|Java functions]] which are imported and invoked from CONFIG}} lock string before query evaluation.* If an XQuery expressionupdating <code>basex:lock</code> is called by a query, a write lock will be applied. It is advisable to explicitly * If another query calls a <code>basex:lock Java </code whenever > function, it performs sensitive read and write operationswill be queued until the first query is evaluated.

==LimitationsPragmas==

Database locking works with all commands unless the glob syntax is used<pre lang='xquery'>update:output((# basex:lock CONFIG #) { file:write('config.xml', such as in the following command call:<config/>)})</pre>

* The write locks is enforced via the {{Code|DROP DB new*Update|update:output}}: drop all databases starting with "new".

===XQuery=Options==

Deciding which databases will be accessed by a complex XQuery expression is a non-trivial task. Database detection works Locks for the following types functions of queriesa module can also be assigned via option declarations:

* {{Code|//item}}, read-locking of the database opened by a client* {{Code|doc(<pre lang='factbookxquery')}}, read-locking of "factbook">* {{Code|collection('db/path/to/docs')}}, read-locking of "db"* {{Code|fndeclare option basex:sum(1 to 100)}}, locking nothing at all* {{Code|delete nodes doc(lock 'testCONFIG')//*[string-length(local-name(.)) > 5]}}, write-locking of "test";

All databases will be locked by queries of the following kindupdate:output(file:write('config.xml', <config/>))</pre>

* {{Code|for $db in ('db1'Once again, 'db2') return doc($db)}}* {{Code|doc(doc('test')/reference/text())}}* <code>let $db := 'test' return insert nodes <test/> into doc($db)</code>a write lock is enforced.

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