> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest_postgres

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Exports

| Name | Kind |
| - | - |
| [`PostgresMemoryStore`](#postgresmemorystore) | Class |
| [`PostgresStore`](#postgresstore) | Class |
| [`PostgresTaskStore`](#postgrestaskstore) | Class |

## PostgresMemoryStore

Persist deliberate memories in a Harnest-owned table in your database.

```python theme={null}
PostgresMemoryStore(
    dsn: str,
    *,
    pool_options: Optional[Mapping[str, Any]] = None,
    setup_schema: bool = True,
) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `dsn` | `str` | Required |
> | `pool_options` | `Optional[Mapping[str, Any]]` | `None` |
> | `setup_schema` | `bool` | `True` |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store = PostgresMemoryStore(dsn=...)
> ```

### PostgresMemoryStore.delete\_all

```python theme={null}
async PostgresMemoryStore.delete_all(scope: harnest.memory.MemoryScope) -> int
```

Erase one explicit namespace through trusted application code only.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `harnest.memory.MemoryScope` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> result = await store.delete_all(scope=...)
> ```

### PostgresMemoryStore.delete\_user

```python theme={null}
async PostgresMemoryStore.delete_user(application_id: str, user_id: str) -> int
```

Erase an explicitly authorized owner without registering any endpoint.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> result = await store.delete_user(application_id=..., user_id=...)
> ```

### PostgresMemoryStore.purge\_expired

```python theme={null}
async PostgresMemoryStore.purge_expired(
    scope: harnest.memory.MemoryScope,
    *,
    limit: int = 100,
    after: str | None = None,
) -> harnest.memory.MemoryCleanupPage
```

Sweep a bounded key page without exposing another user's collection.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `harnest.memory.MemoryScope` | Required |
> | `limit` | `int` | `100` |
> | `after` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> page = await store.purge_expired(scope=...)
> ```

### PostgresMemoryStore.put

```python theme={null}
async PostgresMemoryStore.put(
    record: harnest.memory.MemoryRecord,
    *,
    expected_revision: str | None = None,
) -> harnest.memory.MemoryRecord
```

Validate before atomically persisting a deliberate memory write.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `harnest.memory.MemoryRecord` | Required |
> | `expected_revision` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> record = await store.put(record=...)
> ```

### PostgresMemoryStore.get

```python theme={null}
async PostgresMemoryStore.get(scope: harnest.memory.MemoryScope, key: str) -> harnest.memory.MemoryRecord | None
```

Read only an explicitly scoped live record.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `harnest.memory.MemoryScope` | Required |
> | `key` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> record = await store.get(scope=..., key=...)
> ```

### PostgresMemoryStore.list

```python theme={null}
async PostgresMemoryStore.list(
    scope: harnest.memory.MemoryScope,
    *,
    limit: int = 20,
    after: str | None = None,
) -> harnest.memory.MemoryPage
```

Page records without loading an unbounded provider collection.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `harnest.memory.MemoryScope` | Required |
> | `limit` | `int` | `20` |
> | `after` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> page = await store.list(scope=...)
> ```

### PostgresMemoryStore.search

```python theme={null}
async PostgresMemoryStore.search(
    scope: harnest.memory.MemoryScope,
    query: str,
    *,
    limit: int = 20,
    after: str | None = None,
) -> harnest.memory.MemoryPage
```

Retrieve explicit literal text matches without model or embedding calls.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `harnest.memory.MemoryScope` | Required |
> | `query` | `str` | Required |
> | `limit` | `int` | `20` |
> | `after` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> page = await store.search(scope=..., query=...)
> ```

### PostgresMemoryStore.delete

```python theme={null}
async PostgresMemoryStore.delete(
    scope: harnest.memory.MemoryScope,
    key: str,
    *,
    expected_revision: str | None = None,
) -> bool
```

Remove memory and its indexes with an optional atomic revision fence.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `harnest.memory.MemoryScope` | Required |
> | `key` | `str` | Required |
> | `expected_revision` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> result = await store.delete(scope=..., key=...)
> ```

### PostgresMemoryStore.start

```python theme={null}
async PostgresMemoryStore.start() -> None
```

Open an owned pool and serialize schema setup across replicas.

> [accordion] Example
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> await store.start()
> ```

### PostgresMemoryStore.close

```python theme={null}
async PostgresMemoryStore.close() -> None
```

Close only this provider's connection pool.

> [accordion] Example
>
> ```python theme={null}
> from harnest_postgres import PostgresMemoryStore
>
> store: PostgresMemoryStore
> await store.close()
> ```

## PostgresStore

Store sessions, checkpoints, continuations, tasks and cron together.

```python theme={null}
PostgresStore(
    dsn: str,
    *,
    pool_options: Mapping[str, Any] | None = None,
    lease_pool_options: Mapping[str, Any] | None = None,
    setup_schema: bool = True,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `owner` | `CheckpointOwner` | `'harnest'` |
| `framework` | `str \| None` | `None` |
| `schema_id` | `str` | `'harnest-checkpoint/v1'` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `dsn` | `str` | Required |
> | `pool_options` | `Mapping[str, Any] \| None` | `None` |
> | `lease_pool_options` | `Mapping[str, Any] \| None` | `None` |
> | `setup_schema` | `bool` | `True` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store = PostgresStore(dsn=...)
> ```

### PostgresStore.start

```python theme={null}
async PostgresStore.start() -> None
```

Provision both storage contracts using the combined store's pool.

> [accordion] Example
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> await store.start()
> ```

### PostgresStore.close

```python theme={null}
async PostgresStore.close() -> None
```

Close only pools created and owned by this store.

> [accordion] Example
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> await store.close()
> ```

### PostgresStore.create\_cron

```python theme={null}
async PostgresStore.create_cron(record: CronRecord) -> CronRecord
```

Create a schedule once without reactivating an existing cancelled key.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `CronRecord` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.create_cron(record=...)
> ```

### PostgresStore.get\_cron

```python theme={null}
async PostgresStore.get_cron(*, application_id: str, user_id: str, schedule_id: str) -> CronRecord | None
```

Read a schedule only within its application and owner scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `schedule_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.get_cron(application_id=..., user_id=..., schedule_id=...)
> ```

### PostgresStore.list\_crons

```python theme={null}
async PostgresStore.list_crons(
    *,
    application_id: str,
    user_id: str,
    after: str | None = None,
    limit: int = 100,
) -> tuple[CronRecord, ...]
```

Apply owner filtering and keyset pagination in the database.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.list_crons(application_id=..., user_id=...)
> ```

### PostgresStore.update\_cron

```python theme={null}
async PostgresStore.update_cron(record: CronRecord, *, expected_revision: int) -> CronRecord
```

Replace one schedule conditionally, preserving its immutable identity.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `CronRecord` | Required |
> | `expected_revision` | `int` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.update_cron(record=..., expected_revision=...)
> ```

### PostgresStore.delete\_cron

```python theme={null}
async PostgresStore.delete_cron(*, application_id: str, user_id: str, schedule_id: str) -> bool
```

Delete a schedule using the same owner predicate as reads.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `schedule_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.delete_cron(application_id=..., user_id=..., schedule_id=...)
> ```

### PostgresStore.list\_due\_crons

```python theme={null}
async PostgresStore.list_due_crons(
    *,
    application_id: str,
    now: float,
    after: tuple[float, str] | None = None,
    limit: int = 100,
) -> tuple[CronRecord, ...]
```

Page due schedules in database order without loading inactive rows.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `now` | `float` | Required |
> | `after` | `tuple[float, str] \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.list_due_crons(application_id=..., now=...)
> ```

### PostgresStore.commit\_cron\_occurrence

```python theme={null}
async PostgresStore.commit_cron_occurrence(
    *,
    application_id: str,
    user_id: str,
    schedule_id: str,
    expected_revision: int,
    due_at: float,
    next_run_at: float,
    task: TaskRecord,
) -> TaskRecord | None
```

Atomically enqueue an occurrence and advance its schedule revision.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `schedule_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
> | `due_at` | `float` | Required |
> | `next_run_at` | `float` | Required |
> | `task` | `TaskRecord` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.commit_cron_occurrence(
>     application_id=...,
>     user_id=...,
>     schedule_id=...,
>     expected_revision=...,
>     due_at=...,
>     next_run_at=...,
>     task=...,
> )
> ```

### PostgresStore.enqueue\_task

```python theme={null}
async PostgresStore.enqueue_task(record: TaskRecord) -> TaskRecord
```

Persist an immutable task identity, returning exact idempotent retries.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `TaskRecord` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.enqueue_task(record=...)
> ```

### PostgresStore.get\_task

```python theme={null}
async PostgresStore.get_task(*, application_id: str, job_id: str, user_id: str | None = None) -> TaskRecord | None
```

Read a scoped job; omitted user scope is reserved for trusted workers.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `user_id` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.get_task(application_id=..., job_id=...)
> ```

### PostgresStore.claim\_tasks

```python theme={null}
async PostgresStore.claim_tasks(
    *,
    application_id: str,
    queues: tuple[str, ...],
    now: float,
    lease_seconds: float,
    limit: int = 1,
) -> tuple[TaskRecord, ...]
```

Claim disjoint batches and retire exhausted attempts after crashes.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `queues` | `tuple[str, ...]` | Required |
> | `now` | `float` | Required |
> | `lease_seconds` | `float` | Required |
> | `limit` | `int` | `1` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.claim_tasks(
>     application_id=...,
>     queues=...,
>     now=...,
>     lease_seconds=...,
> )
> ```

### PostgresStore.renew\_task\_lease

```python theme={null}
async PostgresStore.renew_task_lease(
    *,
    application_id: str,
    job_id: str,
    lease_token: str,
    now: float,
    lease_seconds: float,
) -> bool
```

Renew only an unexpired attempt still owned by the calling worker.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `lease_token` | `str` | Required |
> | `now` | `float` | Required |
> | `lease_seconds` | `float` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.renew_task_lease(
>     application_id=...,
>     job_id=...,
>     lease_token=...,
>     now=...,
>     lease_seconds=...,
> )
> ```

### PostgresStore.finish\_task

```python theme={null}
async PostgresStore.finish_task(
    *,
    application_id: str,
    job_id: str,
    lease_token: str,
    now: float,
    status: str,
    result: Any = None,
    failure_code: str | None = None,
    retry_at: float | None = None,
) -> bool
```

Fence completion and retries; terminal transitions erase private input.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `lease_token` | `str` | Required |
> | `now` | `float` | Required |
> | `status` | `str` | Required |
> | `result` | `Any` | `None` |
> | `failure_code` | `str \| None` | `None` |
> | `retry_at` | `float \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.finish_task(
>     application_id=...,
>     job_id=...,
>     lease_token=...,
>     now=...,
>     status=...,
> )
> ```

### PostgresStore.cancel\_task

```python theme={null}
async PostgresStore.cancel_task(*, application_id: str, user_id: str, job_id: str, now: float) -> bool
```

Cancel an owned nonterminal job and revoke any running attempt.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `now` | `float` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.cancel_task(application_id=..., user_id=..., job_id=..., now=...)
> ```

### PostgresStore.list\_task\_metadata

```python theme={null}
async PostgresStore.list_task_metadata(
    *,
    application_id: str,
    user_id: str,
    after: str | None = None,
    limit: int = 100,
) -> dict[str, Any]
```

Push owner, cursor, projection, ordering, and limit into one database query.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.list_task_metadata(application_id=..., user_id=...)
> ```

### PostgresStore.list\_cron\_metadata

```python theme={null}
async PostgresStore.list_cron_metadata(
    *,
    application_id: str,
    user_id: str,
    after: str | None = None,
    limit: int = 100,
) -> dict[str, Any]
```

Read a bounded metadata projection with owner filtering in one SQL query.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.list_cron_metadata(application_id=..., user_id=...)
> ```

### PostgresStore.as\_langgraph\_checkpointer

```python theme={null}
PostgresStore.as_langgraph_checkpointer() -> Any
```

Return one stable native saver for advanced LangGraph construction.

> [accordion] Example
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = store.as_langgraph_checkpointer()
> ```

### PostgresStore.create

```python theme={null}
async PostgresStore.create(*, session_id: str, user_id: str, state: Mapping[str, Any]) -> SessionRecord
```

Create one tenant-scoped session without overwriting conflicts.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `state` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.create(session_id=..., user_id=..., state=...)
> ```

### PostgresStore.get

```python theme={null}
async PostgresStore.get(*, session_id: str, user_id: str) -> SessionRecord | None
```

Read one tenant-scoped session from PostgreSQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.get(session_id=..., user_id=...)
> ```

### PostgresStore.list

```python theme={null}
async PostgresStore.list(*, user_id: str, after: str | None = None, limit: int | None = None) -> Sequence[SessionRecord]
```

Apply tenant filtering and optional keyset pagination in PostgreSQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.list(user_id=...)
> ```

### PostgresStore.put\_a2a\_task

```python theme={null}
async PostgresStore.put_a2a_task(record: A2ATaskRecord) -> A2ATaskRecord
```

Upsert an owner-scoped protobuf snapshot with immutable context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `A2ATaskRecord` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.put_a2a_task(record=...)
> ```

### PostgresStore.get\_a2a\_task

```python theme={null}
async PostgresStore.get_a2a_task(*, application_id: str, user_id: str, task_id: str) -> A2ATaskRecord | None
```

Read one A2A task using its complete application and owner scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `task_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.get_a2a_task(application_id=..., user_id=..., task_id=...)
> ```

### PostgresStore.list\_a2a\_tasks

```python theme={null}
async PostgresStore.list_a2a_tasks(
    *,
    application_id: str,
    user_id: str,
    context_id: str | None = None,
    status: int | None = None,
    status_timestamp_after: str | None = None,
    cursor_task_id: str | None = None,
    limit: int = 51,
) -> A2ATaskPage
```

Apply A2A filters, ordering, and keyset pagination in PostgreSQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `context_id` | `str \| None` | `None` |
> | `status` | `int \| None` | `None` |
> | `status_timestamp_after` | `str \| None` | `None` |
> | `cursor_task_id` | `str \| None` | `None` |
> | `limit` | `int` | `51` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> page = await store.list_a2a_tasks(application_id=..., user_id=...)
> ```

### PostgresStore.delete\_a2a\_task

```python theme={null}
async PostgresStore.delete_a2a_task(*, application_id: str, user_id: str, task_id: str) -> bool
```

Delete one exact A2A owner record without revealing foreign tasks.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `task_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.delete_a2a_task(application_id=..., user_id=..., task_id=...)
> ```

### PostgresStore.update

```python theme={null}
async PostgresStore.update(*, session_id: str, user_id: str, state_delta: Mapping[str, Any]) -> SessionRecord | None
```

Atomically merge a state delta in PostgreSQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `state_delta` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.update(session_id=..., user_id=..., state_delta=...)
> ```

### PostgresStore.delete

```python theme={null}
async PostgresStore.delete(*, session_id: str, user_id: str) -> bool
```

Delete one tenant-scoped session and report whether it existed.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.delete(session_id=..., user_id=...)
> ```

### PostgresStore.acquire

```python theme={null}
PostgresStore.acquire(*, session_id: str, user_id: str) -> AsyncIterator[SessionLease]
```

Hold a cross-replica advisory lock for one session execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `session_id` | `str` | Required |
> | `user_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> async with store.acquire(session_id=..., user_id=...):
>     ...
> ```

### PostgresStore.begin\_run

```python theme={null}
async PostgresStore.begin_run(
    *,
    application_id: str,
    user_id: str,
    session_id: str,
    run_id: str,
    framework: Literal['adk', 'langgraph'],
) -> RunRecord
```

Create an idempotent run while allowing one active run per session.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `framework` | `Literal['adk', 'langgraph']` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.begin_run(
>     application_id=...,
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     framework=...,
> )
> ```

### PostgresStore.get\_run

```python theme={null}
async PostgresStore.get_run(*, scope: RunScope) -> RunRecord | None
```

Read one PostgreSQL checkpoint run through its ownership scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.get_run(scope=...)
> ```

### PostgresStore.get\_checkpoint

```python theme={null}
async PostgresStore.get_checkpoint(
    *,
    scope: RunScope,
    checkpoint_id: str | None = None,
    namespace: str = '',
) -> CheckpointRecord | None
```

Load an exact or newest checkpoint entirely in PostgreSQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `checkpoint_id` | `str \| None` | `None` |
> | `namespace` | `str` | `''` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.get_checkpoint(scope=...)
> ```

### PostgresStore.list\_checkpoints

```python theme={null}
PostgresStore.list_checkpoints(
    *,
    scope: RunScope,
    namespace: str | None = None,
    before: str | None = None,
    limit: int = 20,
) -> AsyncIterator[CheckpointRecord]
```

Push checkpoint filtering, ordering, cursor, and limit into SQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `namespace` | `str \| None` | `None` |
> | `before` | `str \| None` | `None` |
> | `limit` | `int` | `20` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> async for item in store.list_checkpoints(scope=...):
>     ...
> ```

### PostgresStore.put

```python theme={null}
async PostgresStore.put(checkpoint: CheckpointRecord, *, scope: RunScope, expected_revision: int | None) -> CheckpointRecord
```

Allocate a serialized revision and write only on matching CAS state.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `checkpoint` | `CheckpointRecord` | Required |
> | `scope` | `RunScope` | Required |
> | `expected_revision` | `int \| None` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.put(checkpoint=..., scope=..., expected_revision=...)
> ```

### PostgresStore.put\_writes

```python theme={null}
async PostgresStore.put_writes(*, scope: RunScope, checkpoint_id: str, writes: Sequence[CheckpointWrite]) -> None
```

Insert pending writes as one set and ignore existing identities.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `checkpoint_id` | `str` | Required |
> | `writes` | `Sequence[CheckpointWrite]` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> await store.put_writes(scope=..., checkpoint_id=..., writes=...)
> ```

### PostgresStore.get\_writes

```python theme={null}
async PostgresStore.get_writes(*, scope: RunScope, checkpoint_id: str) -> Sequence[CheckpointWrite]
```

Read pending writes for one owned PostgreSQL checkpoint.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `checkpoint_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.get_writes(scope=..., checkpoint_id=...)
> ```

### PostgresStore.get\_writes\_batch

```python theme={null}
async PostgresStore.get_writes_batch(*, scope: RunScope, checkpoint_ids: Sequence[str]) -> Mapping[str, Sequence[CheckpointWrite]]
```

Fetch pending writes for several checkpoints in one query.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `checkpoint_ids` | `Sequence[str]` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.get_writes_batch(scope=..., checkpoint_ids=...)
> ```

### PostgresStore.suspend\_continuation

```python theme={null}
async PostgresStore.suspend_continuation(*, record: ContinuationRecord, external_id: str) -> ContinuationRecord
```

Atomically persist a provider wait and mark its owned run waiting.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `ContinuationRecord` | Required |
> | `external_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.suspend_continuation(record=..., external_id=...)
> ```

### PostgresStore.get\_continuation

```python theme={null}
async PostgresStore.get_continuation(*, scope: RunScope, continuation_id: str) -> ContinuationRecord | None
```

Load one continuation with its complete ownership predicate in SQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `continuation_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.get_continuation(scope=..., continuation_id=...)
> ```

### PostgresStore.get\_provider\_continuation

```python theme={null}
async PostgresStore.get_provider_continuation(*, scope: RunScope, provider: str, continuation_id: str) -> ProviderPendingContinuation | None
```

Load one exact provider wait and its private external identity.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> continuation = await store.get_provider_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
> )
> ```

### PostgresStore.get\_continuation\_by\_external\_id

```python theme={null}
async PostgresStore.get_continuation_by_external_id(
    *,
    application_id: str,
    provider: str,
    external_id: str,
) -> ProviderPendingContinuation | None
```

Use the unique provider key so replica callbacks never scan waits.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `provider` | `str` | Required |
> | `external_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> continuation = await store.get_continuation_by_external_id(
>     application_id=...,
>     provider=...,
>     external_id=...,
> )
> ```

### PostgresStore.list\_pending\_continuations

```python theme={null}
async PostgresStore.list_pending_continuations(
    *,
    application_id: str,
    provider: str,
    after: str | None = None,
    limit: int = 100,
) -> Sequence[ProviderPendingContinuation]
```

Push provider reconciliation filtering and pagination into PostgreSQL.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `provider` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> result = await store.list_pending_continuations(application_id=..., provider=...)
> ```

### PostgresStore.resolve\_continuation

```python theme={null}
async PostgresStore.resolve_continuation(
    *,
    scope: RunScope,
    provider: str,
    external_id: str,
    schema_id: str,
    result: Any = None,
    failure: ContinuationFailure | None = None,
) -> ContinuationRecord
```

Commit one validated provider outcome with an indexed SQL CAS.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `external_id` | `str` | Required |
> | `schema_id` | `str` | Required |
> | `result` | `Any` | `None` |
> | `failure` | `ContinuationFailure \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.resolve_continuation(
>     scope=...,
>     provider=...,
>     external_id=...,
>     schema_id=...,
> )
> ```

### PostgresStore.claim\_continuation

```python theme={null}
async PostgresStore.claim_continuation(
    *,
    scope: RunScope,
    provider: str,
    continuation_id: str,
    expected_revision: int,
) -> ContinuationRecord
```

Claim an outcome and resume its run in one PostgreSQL statement.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.claim_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
>     expected_revision=...,
> )
> ```

### PostgresStore.cancel\_continuation

```python theme={null}
async PostgresStore.cancel_continuation(
    *,
    scope: RunScope,
    provider: str,
    continuation_id: str,
    expected_revision: int,
    failure: ContinuationFailure,
) -> ContinuationRecord
```

Fail a pending continuation and cancel its waiting run atomically.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
> | `failure` | `ContinuationFailure` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.cancel_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
>     expected_revision=...,
>     failure=...,
> )
> ```

### PostgresStore.arm\_continuation

```python theme={null}
async PostgresStore.arm_continuation(
    *,
    scope: RunScope,
    provider: str,
    continuation_id: str,
    expected_revision: int,
) -> ContinuationRecord
```

Arm one wait with a SQL CAS after native checkpoint persistence.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.arm_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
>     expected_revision=...,
> )
> ```

### PostgresStore.transition

```python theme={null}
async PostgresStore.transition(
    *,
    scope: RunScope,
    expected_status: RunStatus,
    status: RunStatus,
    pending_action: PendingAction | None = None,
) -> RunRecord
```

Apply a validated status transition with one SQL compare-and-swap.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `expected_status` | `RunStatus` | Required |
> | `status` | `RunStatus` | Required |
> | `pending_action` | `PendingAction \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> record = await store.transition(scope=..., expected_status=..., status=...)
> ```

### PostgresStore.delete\_run

```python theme={null}
async PostgresStore.delete_run(*, scope: RunScope) -> None
```

Delete a run and cascade its private checkpoint data.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresStore
>
> store: PostgresStore
> await store.delete_run(scope=...)
> ```

## PostgresTaskStore

Persist jobs and schedules with transactional claims and fenced leases.

`_pool` supports composing this provider with the combined session store;
externally supplied pools remain owned by their caller.

```python theme={null}
PostgresTaskStore(
    dsn: str,
    *,
    pool_options: Mapping[str, Any] | None = None,
    setup_schema: bool = True,
) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `dsn` | `str` | Required |
> | `pool_options` | `Mapping[str, Any] \| None` | `None` |
> | `setup_schema` | `bool` | `True` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store = PostgresTaskStore(dsn=...)
> ```

### PostgresTaskStore.start

```python theme={null}
async PostgresTaskStore.start() -> None
```

Open one pool and install or validate the durable schema.

> [accordion] Example
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> await store.start()
> ```

### PostgresTaskStore.close

```python theme={null}
async PostgresTaskStore.close() -> None
```

Close only the pool opened by this instance.

> [accordion] Example
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> await store.close()
> ```

### PostgresTaskStore.create\_cron

```python theme={null}
async PostgresTaskStore.create_cron(record: CronRecord) -> CronRecord
```

Create a schedule once without reactivating an existing cancelled key.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `CronRecord` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> record = await store.create_cron(record=...)
> ```

### PostgresTaskStore.get\_cron

```python theme={null}
async PostgresTaskStore.get_cron(*, application_id: str, user_id: str, schedule_id: str) -> CronRecord | None
```

Read a schedule only within its application and owner scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `schedule_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> record = await store.get_cron(application_id=..., user_id=..., schedule_id=...)
> ```

### PostgresTaskStore.list\_crons

```python theme={null}
async PostgresTaskStore.list_crons(
    *,
    application_id: str,
    user_id: str,
    after: str | None = None,
    limit: int = 100,
) -> tuple[CronRecord, ...]
```

Apply owner filtering and keyset pagination in the database.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.list_crons(application_id=..., user_id=...)
> ```

### PostgresTaskStore.update\_cron

```python theme={null}
async PostgresTaskStore.update_cron(record: CronRecord, *, expected_revision: int) -> CronRecord
```

Replace one schedule conditionally, preserving its immutable identity.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `CronRecord` | Required |
> | `expected_revision` | `int` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> record = await store.update_cron(record=..., expected_revision=...)
> ```

### PostgresTaskStore.delete\_cron

```python theme={null}
async PostgresTaskStore.delete_cron(*, application_id: str, user_id: str, schedule_id: str) -> bool
```

Delete a schedule using the same owner predicate as reads.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `schedule_id` | `str` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.delete_cron(application_id=..., user_id=..., schedule_id=...)
> ```

### PostgresTaskStore.list\_due\_crons

```python theme={null}
async PostgresTaskStore.list_due_crons(
    *,
    application_id: str,
    now: float,
    after: tuple[float, str] | None = None,
    limit: int = 100,
) -> tuple[CronRecord, ...]
```

Page due schedules in database order without loading inactive rows.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `now` | `float` | Required |
> | `after` | `tuple[float, str] \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.list_due_crons(application_id=..., now=...)
> ```

### PostgresTaskStore.commit\_cron\_occurrence

```python theme={null}
async PostgresTaskStore.commit_cron_occurrence(
    *,
    application_id: str,
    user_id: str,
    schedule_id: str,
    expected_revision: int,
    due_at: float,
    next_run_at: float,
    task: TaskRecord,
) -> TaskRecord | None
```

Atomically enqueue an occurrence and advance its schedule revision.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `schedule_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
> | `due_at` | `float` | Required |
> | `next_run_at` | `float` | Required |
> | `task` | `TaskRecord` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> record = await store.commit_cron_occurrence(
>     application_id=...,
>     user_id=...,
>     schedule_id=...,
>     expected_revision=...,
>     due_at=...,
>     next_run_at=...,
>     task=...,
> )
> ```

### PostgresTaskStore.enqueue\_task

```python theme={null}
async PostgresTaskStore.enqueue_task(record: TaskRecord) -> TaskRecord
```

Persist an immutable task identity, returning exact idempotent retries.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `TaskRecord` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> record = await store.enqueue_task(record=...)
> ```

### PostgresTaskStore.get\_task

```python theme={null}
async PostgresTaskStore.get_task(*, application_id: str, job_id: str, user_id: str | None = None) -> TaskRecord | None
```

Read a scoped job; omitted user scope is reserved for trusted workers.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `user_id` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> record = await store.get_task(application_id=..., job_id=...)
> ```

### PostgresTaskStore.claim\_tasks

```python theme={null}
async PostgresTaskStore.claim_tasks(
    *,
    application_id: str,
    queues: tuple[str, ...],
    now: float,
    lease_seconds: float,
    limit: int = 1,
) -> tuple[TaskRecord, ...]
```

Claim disjoint batches and retire exhausted attempts after crashes.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `queues` | `tuple[str, ...]` | Required |
> | `now` | `float` | Required |
> | `lease_seconds` | `float` | Required |
> | `limit` | `int` | `1` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.claim_tasks(
>     application_id=...,
>     queues=...,
>     now=...,
>     lease_seconds=...,
> )
> ```

### PostgresTaskStore.renew\_task\_lease

```python theme={null}
async PostgresTaskStore.renew_task_lease(
    *,
    application_id: str,
    job_id: str,
    lease_token: str,
    now: float,
    lease_seconds: float,
) -> bool
```

Renew only an unexpired attempt still owned by the calling worker.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `lease_token` | `str` | Required |
> | `now` | `float` | Required |
> | `lease_seconds` | `float` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.renew_task_lease(
>     application_id=...,
>     job_id=...,
>     lease_token=...,
>     now=...,
>     lease_seconds=...,
> )
> ```

### PostgresTaskStore.finish\_task

```python theme={null}
async PostgresTaskStore.finish_task(
    *,
    application_id: str,
    job_id: str,
    lease_token: str,
    now: float,
    status: str,
    result: Any = None,
    failure_code: str | None = None,
    retry_at: float | None = None,
) -> bool
```

Fence completion and retries; terminal transitions erase private input.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `lease_token` | `str` | Required |
> | `now` | `float` | Required |
> | `status` | `str` | Required |
> | `result` | `Any` | `None` |
> | `failure_code` | `str \| None` | `None` |
> | `retry_at` | `float \| None` | `None` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.finish_task(
>     application_id=...,
>     job_id=...,
>     lease_token=...,
>     now=...,
>     status=...,
> )
> ```

### PostgresTaskStore.cancel\_task

```python theme={null}
async PostgresTaskStore.cancel_task(*, application_id: str, user_id: str, job_id: str, now: float) -> bool
```

Cancel an owned nonterminal job and revoke any running attempt.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `job_id` | `str` | Required |
> | `now` | `float` | Required |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.cancel_task(application_id=..., user_id=..., job_id=..., now=...)
> ```

### PostgresTaskStore.list\_task\_metadata

```python theme={null}
async PostgresTaskStore.list_task_metadata(
    *,
    application_id: str,
    user_id: str,
    after: str | None = None,
    limit: int = 100,
) -> dict[str, Any]
```

Push owner, cursor, projection, ordering, and limit into one database query.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.list_task_metadata(application_id=..., user_id=...)
> ```

### PostgresTaskStore.list\_cron\_metadata

```python theme={null}
async PostgresTaskStore.list_cron_metadata(
    *,
    application_id: str,
    user_id: str,
    after: str | None = None,
    limit: int = 100,
) -> dict[str, Any]
```

Read a bounded metadata projection with owner filtering in one SQL query.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest_postgres import PostgresTaskStore
>
> store: PostgresTaskStore
> result = await store.list_cron_metadata(application_id=..., user_id=...)
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.