Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
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.==XQuery Locks==
==External Side Effects==By default, access to external resources (files on hard disk, HTTP requests, ...) is not controlled by the transaction monitor of BaseX. You can use custom XQuery locks to do so:
Access to external resources (files on hard disk===Options, HTTP requestsPragmas, ...) is not controlled by the transaction monitor of BaseX unless specified by the user.Annotations===
===XQuery Locking Options==={{Mark|Introduced with Version 9.1}}: locks via pragmas and function annotations.
Custom locks * You can be acquired by setting the BaseX-specific XQuery options {{Code|query:declare custom read-lock}} and {{Code|query:write-locks via options, pragmas or function annotations.* The value of the lock}}. Multiple option declarations may occur in the prolog of a query, but contain one or multiple values can also be lock keys (separated with commas in a single declaration). The default value is an empty string. These locks are in another namespace than * Similar to the internal database names: the lock value {{Code|factbook}} locks, write locks block all other operations while read locks allow parallel access.* The internal locks and XQuery locks can co-exist (there will not be no conflicts, even if your lock string equals the name of a database named factbookthat will be locked by the transaction manager).
These option declarations will put read locks on ''foo''In the following module, ''bar'' and ''batz'' and a lock annotations are used to prevent concurrent write lock operations on ''quix''the same file:
===GUI===
Database locking is currently disabled if the BaseX GUI is used.
==Process Locking==
In order to enable locking on global (process) level, the option <code>[[Options#GLOBALLOCK|GLOBALLOCK]]</code> can be set to {{Code|true}}. This can e.g. be done by editing your {{Code|.basex}} file (see [[Options]] for more details). If process locking is active, a process that performs write operations will queue all other operations.
[[Category:Server]]
[[Category:Internals]]
→Options, Pragmas, Annotations
Please note that:
* 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 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.
* 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:xquery">
module namespace config = 'config'; declare option query%basex:read-lock "foo,bar";('CONFIG') function config:read() {declare option query file:read-lock "batz"text('config.txt')}; declare option query%basex:write-lock "quix"('CONFIG') function config:write($data) { file:write-text('config.txt', $data)};
</pre>
Some explanations:
* If a query calls the <code>config:read</code> function, a read lock will be acquired for the user-defined {{Code|CONFIG}} lock string before query evaluation.
* If <code>config:write</code> is called by a query, a write lock on this lock string will be set for this query.
* If a query calls <code>config:write</code>, it will be queued until there is no running query left that has {{Code|CONFIG}} locked.
* If the writing query will be evaluated, all other queries that will set a {{Code|CONFIG}} lock (reading or writing) will have to wait.
Local locks can also be declared via pragmas:
<pre class="brush:xquery">
(# basex:write-lock CONFIG #) {
file:write('config.xml', <config/>)
}
</pre>
Locks for the functions of a module can be assigned via option declarations:
<pre class="brush:xquery">
declare option basex:write-lock 'CONFIG';
file:write('config.xml', <config/>)
</pre>
Before {{Version|9.1}}, locks were declared in the {{Code|query}} namespace.
===Java Modules===
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 <code>[[Options#QUERYINFO|QUERYINFO]]</code> to {{Code|true}}) to find out which databases have been locked by a query.
=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 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.".
Please note that you cannot 100% rely on this mechanism, as it is not possible to synchronize operations across different JVMs. You will be safe when using the client/server or HTTP architecture.
=Changelog=
;Version 9.1
* Updated: Query lock options were moved from {{Code|query}} to {{Code|basex}} namespace.
;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.
