Metadata-Version: 2.4
Name: nl2data-workflow-postgres
Version: 0.1.0
Summary: PostgreSQL-backed durable workflow state backend for nl2data-core.
Author: NL2Data Contributors
License: Apache-2.0
Keywords: nl2data,postgresql,workflow,state,lease,idempotency
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: nl2data-core>=0.1.0
Requires-Dist: psycopg[binary,pool]<4,>=3.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"

# nl2data-workflow-postgres

Optional PostgreSQL-backed durable workflow state backend for `nl2data-core`.

## Overview

This package provides a production-ready PostgreSQL implementation of the core workflow state-store contracts (`StateStore`, `IdempotencyStore`, `WorkflowLeaseStore`, and `FencedStateStore`) from `nl2data-core`. It persists safe workflow snapshots, idempotency records, and execution leases in PostgreSQL while keeping `psycopg` lazy and optional.

Base `nl2data` / `nl2data-core` imports remain PostgreSQL-free; the driver is loaded only when a `PostgreSQLStateStore` is constructed.

## Installation

```bash
pip install nl2data-workflow-postgres
```

This also installs `psycopg[binary,pool]>=3.1,<4` and `nl2data-core>=0.1.0`.

## Quick Start

```python
from nl2data_core.workflow import WorkflowState
from nl2data_workflow_postgres import PostgreSQLStateStore, WorkflowPostgresConfig

store = PostgreSQLStateStore(
    dsn="postgresql://user:pass@localhost/db",
    config=WorkflowPostgresConfig(namespace="workflow"),
)

# store.create(state), store.update(...), store.acquire_lease(...), etc.
```

## Public surface

```python
from nl2data_workflow_postgres import (
    MIGRATIONS,
    SUPPORTED_SCHEMA_VERSION,
    SQL_TEMPLATES,
    PostgreSQLStateStore,
    WorkflowPostgresConfig,
    build_pool,
    driver_available,
)
```

- `PostgreSQLStateStore` — the core store-contract implementation
  (`StateStore`, `IdempotencyStore`, `WorkflowLeaseStore`, `FencedStateStore`)
  with compare-and-set updates and fenced lease checks.
- `WorkflowPostgresConfig` — bounded pool/timeout/TTL configuration with a
  derived tenant-scope namespace.
- `MIGRATIONS` / `SUPPORTED_SCHEMA_VERSION` — versioned DDL in a package-owned
  schema namespace.
- `build_pool` / `driver_available` — lazy psycopg pool construction and
  driver availability probes that never import the driver.

## Compatibility

The in-core `nl2data_core.workflow.postgres_*` modules were removed. All
PostgreSQL workflow state ships from this package; import from
`nl2data_workflow_postgres` directly. The core distribution no longer ships a
PostgreSQL workflow backend.

## Features

- **Durable workflow state** with versioned safe snapshots and compare-and-set semantics
- **Idempotency records** with reservation, conflict detection, and terminal outcome references
- **Lease ownership** with monotonic fencing tokens, renewal, release, and stale-worker takeover
- **Tenant-scope isolation** via opaque fingerprints and derived schema namespaces
- **Versioned migrations** in a package-owned schema namespace
- **Normalized errors** without leaking DSNs, credentials, or raw backend text
- **Lazy driver loading** so the base framework never imports `psycopg`

## Development

Install in editable mode from the repository root:

```bash
pip install -e packages/nl2data-workflow-postgres
```

Run package tests:

```bash
pytest packages/nl2data-workflow-postgres/tests -q
```
