Changes

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=

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.

NotePlease note that:An unexpected abort of the server during a transaction, caused by a hardwarefailure or power cut, will probably lead to an inconsistent database state if a transaction was active at the shutdown time. So we advise to usethe [[Commands#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.

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

BaseX 7provides 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.6 introduces * 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 level. Writing transactions do A will not necessarily block all other transactions any moreoperations 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 limited 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. ==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 setting 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')</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="top"| <code>declare variables $db external;<br/>db:get($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>| Read lock of {{Code|db1}} and {{Code|db2}}, as the query is [[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 [[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, as the query is simplified 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())</code>| The name of the database to be opened will only be 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#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 [[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:

Deadlocks are prevented by using preclaiming two phase locking. Execution is starvation-free as lock aquiration is queued per database. Due to In the specifics of XQuery Updatefollowing module, all updates lock annotations are written at the end of used to prevent concurrent write operations on the query. Locking is strict with the exception that databases for which BaseX recognizes it will not write to are downgraded to read locks.same file:

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

* If a query calls a reading <code>basex:lock</code> function, a read lock will be acquired for the user-defined {{Code|DROP DB new*CONFIG}}lock string before query evaluation.* If an updating <code>basex:lock</code> is called by a query, a write lock will be applied.* If another query calls a <code>basex: drop all databases starting with "new"lock</code> function, 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<pre lang='xquery'>update:output((# basex:lock CONFIG #) { file:write('config.xml', all of these can be executed in parallel:<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>let $db := 'factbook' return doc($db)</code>, will read lock globally: referencing database names isn’t supported yet* {{Code|Locks for $db in ('factbook') return doc($db)}}, will read lock globally: ditto* {{Code|doc(doc('test')/reference/text())}}, will read lock globally: ditto* <code>let $db := 'test' return insert nodes <test/> into doc($db)</code>, will write lock globallythe functions of a module can also be assigned via option declarations: ditto

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

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

==How to disableJava Modules==

In order to disable traditional process locking, the option <code>Locks can also be acquired on [[OptionsJava Bindings#GLOBALLOCKLocking|GLOBALLOCKJava functions]]</which are imported and invoked from an XQuery expression. It is advisable to explicitly lock Java code> can be set to {{Code|false}}. This can e.g. be done by editing your {{Code|.basex}} file (see [[Options]] for more details). To enable whenever it again, set it to [[Code|true}}performs sensitive read and write 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.

;Version 710.0* Updated: Lock detection was improved by splitting compilation into multiple steps.6

;Version 9.4* AddedUpdated: database locking introduced, replacing process lockingSingle lock option for reads and writes.

;Version 79.21* Updated: Query lock options were moved from {{Code|query}} to {{Code|basex}} namespace.1

;Version 8.6* Updated: pin files replaced with shared/exclusive filesystem lockingNew {{Option|FAIRLOCK}} option, improved detection of lock patterns.

;Version 7.28* Added: Locks can also be acquired on [[Java Bindings#Locking|Java functions]].

;Version 7.6* Added: pin files to mark open databasesdatabase locking introduced, replacing process locking.

;Version 7.2.1* Updated: pin files replaced with shared/exclusive filesystem locking.

;Version 7.2* Added: update lock pin filesto mark open databases.

[[Category:Server]];Version 7.1[[Category* Added:Internals]]update lock files.