mirror of
https://github.com/inventree/InvenTree.git
synced 2026-11-18 14:07:41 +00:00
[bug] API row locking (#13274)
* row locking on patch * row-level locking on action endpoints * apply row locking to barcode actions * additional row-locking for build actions * rename exception class * updated docs * Add specific error code * Fix translated text * Handle AttributeError
This commit is contained in:
1 parent
3572714f5f
commit
b2a9218cfb
16 files changed
+1125
-41
No files matched your search
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
@@ -128,6 +128,13 @@ An InvenTree process (web server or background worker) reloaded its plugins, but
|
||||
|
||||
The affected process stops reloading its plugins to prevent an endless reload loop. Restart all InvenTree server and background worker processes to resolve this error. See [reloading plugins](../plugins/install.md#reloading-plugins) for further information.
|
||||
|
||||
#### INVE-E21
|
||||
**Resource locked by another process - Backend**
|
||||
|
||||
An API request attempted to modify an object that is currently locked by another long-running process. This typically occurs when multiple processes are trying to update the same object concurrently.
|
||||
|
||||
The request will return a `409 Conflict` response. Retry the request after the other process has completed its operation.
|
||||
|
||||
## Warning Codes
|
||||
|
||||
### INVE-W (InvenTree Warning)
|
||||
|
||||
@@ -312,6 +312,48 @@ If running with a SQLite database backend, the following additional options are
|
||||
{{ configsetting("INVENTREE_DB_TIMEOUT", default="10") }} Database connection timeout (s) |
|
||||
| `INVENTREE_DB_WAL_MODE` | database.wal_mode | True | Enable Write-Ahead Logging (WAL) mode for SQLite databases |
|
||||
|
||||
### Concurrent Updates
|
||||
|
||||
InvenTree is a multi-user system, and it also runs [background tasks](./processes.md#background-worker) which modify the database. This means that the same database record can be changed by two processes at (almost) the same time - for example, a user edits a build order while a background task is completing the outputs of that same build order.
|
||||
|
||||
If this is not managed, one process can silently overwrite the changes made by the other (a "lost update"), as each process saves the data it read *before* the other process finished.
|
||||
|
||||
#### How Contention is Managed
|
||||
|
||||
InvenTree relies on *row-level locking* in the database to prevent lost updates:
|
||||
|
||||
- **Editing an object:** When an existing object is updated via the API, the database row is locked *before* the object is read. The object is then validated and saved within a single database transaction, and the lock is released when the request completes.
|
||||
- **Performing an action:** Actions against an existing object (e.g. issuing, completing or cancelling an order, completing build outputs, receiving items, assigning a barcode) are handled in the same way: the target object is locked for the duration of the request, and if the action fails then none of its changes are saved.
|
||||
- **Background tasks:** Tasks which adjust quantities (e.g. completing build outputs, consuming allocated stock, receiving items) lock the rows they work on, and re-read the current values before changing them.
|
||||
|
||||
A request waits for a short time (around two seconds) for a lock to be released, which is long enough for most operations to complete without the user noticing. If the object is still locked after this time (e.g. a background task is processing a large number of items), the request is rejected with a `409 Conflict` response, and no changes are made. The request can safely be submitted again once the other process has finished.
|
||||
|
||||
In the user interface, this is displayed as an error message at the top of the form:
|
||||
|
||||
{{ image("start/contention_error.png", "Error message displayed when an item is locked by another process") }}
|
||||
|
||||
!!! tip "Try Again"
|
||||
This message does not indicate a problem with the data which was entered. Wait a few moments for the other process to complete, and then submit the form again.
|
||||
|
||||
#### Where Failures Can Still Occur
|
||||
|
||||
Row-level locking prevents the most common lost updates, but it cannot cover every case:
|
||||
|
||||
- **Stale forms:** A lock is only held while a request is being processed, not while a form is open. If an object is changed by someone else after a form has been opened, submitting the form overwrites those changes with the (older) values displayed in the form.
|
||||
- **Operations across many objects:** Operations which act on many objects at once (e.g. bulk stock adjustments) are not locked as a single unit. Two such operations which overlap may have to wait for each other, and one of them may fail.
|
||||
- **Deadlocks:** If two processes each wait for a lock held by the other, the database aborts one of them. The aborted request (or background task) fails with an error, and its changes are not saved.
|
||||
- **Plugins and custom code:** Code which loads an object, modifies it and saves it without locking the row (e.g. a third-party plugin, or the admin interface) is not protected, and can overwrite a concurrent change.
|
||||
- **Serializable isolation:** If the `INVENTREE_DB_ISOLATION_SERIALIZABLE` option is enabled, the database itself rejects any transaction which conflicts with another. Data is never silently overwritten in this mode, but InvenTree does not automatically retry a rejected transaction: a request or background task which conflicts with another fails with a server error, and must be retried manually.
|
||||
|
||||
#### SQLite Limitations
|
||||
|
||||
SQLite does not support row-level locking - instead, the entire database is locked while a process is writing to it. As a result:
|
||||
|
||||
- The protections described above are **not available**. A concurrent edit can still overwrite changes made by another process.
|
||||
- Only one process can write to the database at a time. A process which cannot obtain the database lock within the configured `INVENTREE_DB_TIMEOUT` fails with a "database is locked" error.
|
||||
|
||||
This is one of the reasons that SQLite is not recommended for production use, particularly where multiple users (or a background worker) are active at the same time. Use PostgreSQL or MySQL for any installation where data integrity is important.
|
||||
|
||||
## Caching
|
||||
|
||||
InvenTree can be configured to use [redis](https://redis.io) as a global cache backend.
|
||||
|
||||
Reference in new issue
Block a user