---
url: "https://vueda.dev/v3/reference/api/py/vueda.vdq.utils.md"
title: "vdq.utils"
---

# vdq.utils

## Overview

Row locks on VDQ queue items.

## `lock_queue_item` {#lock_queue_item}

Yield the queue item ``pk`` locked with ``SELECT FOR UPDATE`` inside a transaction. Yields ``None`` when
the item does not exist, or when ``skip_locked`` is true and another transaction holds the lock.

### Signature {#lock_queue_item-signature}

`lock_queue_item(pk, skip_locked)`

#### Parameters {#lock_queue_item-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="lock_queue_item-param-pk">pk</span> |  | yes |  |  |
| <span id="lock_queue_item-param-skip_locked">skip_locked</span> |  | no | `True` |  |

#### Returns {#lock_queue_item-returns}

`contextlib.AbstractContextManager[vueda.vdq.models.QueueItem | None]`

### Source {#lock_queue_item-source}

`server/vueda/vdq/utils.py:34`

## `with_locked_queue_item` {#with_locked_queue_item}

Run ``operation`` on the locked queue item in its own transaction, and return its result.

``operation`` receives ``None`` when the row does not exist. The lock waits for another transaction that holds
the row, for at most ``LOCK_TIMEOUT``. At REPEATABLE READ, a transaction that waited for a holder that updated
the row fails with a serialization error. A stale read of workflow state fails the same way when it is written.
Either failure reruns ``operation`` in a new transaction, up to ``LOCK_ATTEMPTS`` times, so ``operation`` must be
safe to run again. Call this outside any transaction: rolling back to a savepoint does not give the rerun a fresh
snapshot.

### Signature {#with_locked_queue_item-signature}

`with_locked_queue_item(pk, operation)`

#### Parameters {#with_locked_queue_item-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="with_locked_queue_item-param-pk">pk</span> |  | yes |  |  |
| <span id="with_locked_queue_item-param-operation">operation</span> | `collections.abc.Callable[[vueda.vdq.models.QueueItem \| None], T]` | yes |  |  |

#### Returns {#with_locked_queue_item-returns}

`T`

### Source {#with_locked_queue_item-source}

`server/vueda/vdq/utils.py:45`

## Source

`server/vueda/vdq/utils.py`